Heartz application

Technology Stack

• Backend: Golang
• Frontend: SvelteKit in SPA mode
• Database: SQLite

Features

• Everything is embedded into a single executable for easy deployment.
• Authentication is handled with JWT (JSON Web Tokens) and includes basic CSRF (Cross-Site Request Forgery) prevention using SameSite cookies.
• Enhanced type-safety for API and database queries with Protocol Buffers and SQLC.

Project structure

The project structure is loosely based on the MVC (Model-View-Controller) pattern, promoting a clear separation of concerns.

backend/
├── models/
│   ├── query.sql                       # SQL queries for database interactions
│   ├── schema.sql                      # Database schema definitions
│   └── gen/                            # The SQLC generated code
├── views/
│   ├── embed.go                        # Embed and serve the frontend
│   └── gen/                            # The bundled SvelteKit frontend
├── controllers/
│   ├── controller.go                   # The base controller for handling requests
│   ├── <endpoint_1>.go
│   │   ...
│   ├── <endpoint_n>.go
│   └── gen/                            # The generated protobuf Golang code
└── main.go                             # The entrypoint of the application
frontend/                               # Standard SvelteKit source structure
├── lib/
│   ├── components/
│   │   ├── <component_1>.svelte
│   │   │   ...
│   │   └── <component_n>.svelte
│   └── gen/                            # The generated protobuf TypeScript code
├── routes/
│   ├── <route_1>/
│   │   ...
│   └── <route_n>/
│       ├── +page.svelte                # Svelte page component
│       └── +page.ts                    # TypeScript logic for data loading
└── static/                             # Static assets (images, robots.txt, etc.)

Building the Application

To build the application, run the following command:

npm run build

This command will execute all code generation processes, bundle the frontend assets, and compile the backend into a single executable.

Usage

Generating a Salt for Password Hashing

To generate a secure salt for password hashing, use the following command:

openssl rand -hex 32

Starting the Server

To start the server, use the generated salt as an environment variable:

SALT=<generated salt> ./app

Configuration via Bash Script

Alternatively, you can create a shell script to serve as a configuration file for the server. Below is an example of how to set the PORT and DB_PATH environment variables in the script:

#!/bin/sh

export PORT="8080"
export DB_PATH="app.db"
export SALT="<generated salt>"

# Start the server
./app

Make sure to give execution permissions to your script:

chmod +x your_script.sh

Then, you can run your script to start the server with the specified configuration:

./your_script.sh

Development resources

• Svelte documentation: https://svelte.dev/docs/
• Golang standard library documentation: https://pkg.go.dev/std/
• SQLC documentation: https://docs.sqlc.dev/en/latest/
• Protocol Buffers:
  • Message format: https://protobuf.dev/programming-guides/encoding/
  • TypeScript: https://github.com/bufbuild/protobuf-es/blob/main/MANUAL.md
  • Golang: https://protobuf.dev/getting-started/gotutorial/