# @lfk/backend

Backend Server

## Prerequisites

This project uses **Bun** as the runtime and package manager. Install Bun first:

```bash
# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"
```

Or visit [bun.sh](https://bun.sh) for other installation methods.

## Quickstart 🐳
> Use this to run the backend with a PostgreSQL db in Docker

1. Clone the repo or copy the docker-compose
2. Run in the folder that contains the docker-compose file: `docker-compose up -d`
3. Visit http://127.0.0.1:4010/api/docs to check if the server is running
4. You can now use the default admin user (`demo:demo`)

## Dev Setup 🛠
> Local dev setup utilizing SQLite3 as the database and NATS for caching.

1. Rename the `.env.example` file to `.env` (you can adjust app port and other settings if needed)
2. Start NATS (required for KV cache):
```bash
docker-compose up -d nats
```
3. Install dependencies:
```bash
bun install
```
4. Start the server:
```bash
bun run dev
```

**Note**: Bun cannot run TypeScript source files directly due to circular TypeORM dependencies. The `dev` script automatically builds and runs the compiled output. For hot-reload during development, you may need to rebuild manually after code changes.

### Run Tests
```bash
# Run tests once (server has to be running)
bun test

# Run test in watch mode (reruns on change)
bun run test:watch

# Run test in CI mode (automatically starts the dev server)
bun run test:ci
```

### Run Benchmarks
```bash
# Start the server first
bun run dev

# In another terminal:
bun run benchmark
```

### Generate Docs
```bash
bun run docs
```

### Other Commands
```bash
# Build for production
bun run build

# Start production server
bun start

# Seed database with test data
bun run seed

# Export OpenAPI spec
bun run openapi:export

# Generate license report
bun run licenses:export

# Generate changelog
bun run changelog:export
```

## ENV Vars
> You can provide them via .env file or docker env vars.
> You can use the `test:ci:generate_env` package script to generate an example env (uses placeholder data for test server and ignores the errors).

| Name                      | Type               | Default                    | Description                                                                                                      |
| ------------------------- | ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| APP_PORT                  | Number             | 4010                       | The port the backend server listens on. Is optional.                                                            |
| DB_TYPE                   | String             | N/A                        | The type of the db you want to use. Supported by TypeORM. Possible: `sqlite`, `mysql`, `postgresql`              |
| DB_HOST                   | String             | N/A                        | The db's host IP address/FQDN or file path for sqlite                                                           |
| DB_PORT                   | String             | N/A                        | The db's port                                                                                                    |
| DB_USER                   | String             | N/A                        | The user for accessing the db                                                                                    |
| DB_PASSWORD               | String             | N/A                        | The user's password for accessing the db                                                                         |
| DB_NAME                   | String             | N/A                        | The db's name                                                                                                    |
| NODE_ENV                  | String             | dev                        | The app's env - influences debug info. When set to "test", mailing errors get ignored.                          |
| POSTALCODE_COUNTRYCODE    | String/CountryCode | N/A                        | The country code used to validate address postal codes                                                           |
| PHONE_COUNTRYCODE         | String/CountryCode | null (international)       | The country code used to validate phone numbers                                                                  |
| SEED_TEST_DATA            | Boolean            | false                      | If you want the app to seed example data, set this to true                                                       |
| STATION_TOKEN_SECRET      | String             | N/A                        | Secret key for HMAC-SHA256 station token generation (min 32 chars). **Required.**                               |
| NATS_URL                  | String(URL)        | nats://localhost:4222      | NATS server connection URL for KV cache                                                                          |
| NATS_PREWARM              | Boolean            | false                      | Preload all runner state into NATS cache at startup (eliminates DB reads on first scan)                         |
| MAILER_URL                | String(URL)        | N/A                        | The mailer's base URL (no trailing slash)                                                                       |
| MAILER_KEY                | String             | N/A                        | The mailer's API key                                                                                             |
| SELFSERVICE_URL           | String(URL)        | N/A                        | The link to selfservice (no trailing slash)                                                                      |
| IMPRINT_URL               | String(URL)        | /imprint                   | The link to an imprint page for the system (defaults to the frontend's imprint)                                 |
| PRIVACY_URL               | String(URL)        | /privacy                   | The link to a privacy page for the system (defaults to the frontend's privacy page)                             |


## Recommended Editor

[Visual Studio Code](https://code.visualstudio.com/)

### Recommended Extensions

* will be automatically recommended via ./vscode/extensions.json

## Staging
### Branches & Tags
* vX.Y.Z: Release tags created from the main branch
   * The version numbers follow the semver standard
   * A new release tag automaticly triggers the release ci pipeline
* main: Protected "release" branch
   * The latest tag of the docker image get's build from this
* dev: Current dev branch for merging the different feature branches and bugfixes
   * New releases get created as tags from this   
   * The dev tag of the docker image get's build from this
   * Only push minor changes to this branch!
   * To merge a feature branch into this please create a pull request
* feature/xyz: Feature branches - naming scheme: `feature/issueid-title`
* bugfix/xyz: Branches for bugfixes - naming scheme:`bugfix/issueid-title`