Developer Guide#

Prerequisites#

Bun installed (v1.x or newer).

Steps to Run#

Clone the repository and navigate into the directory:

git clone https://github.com/svyatoslav-kubakh/podhound.git
cd podhound

Install dependencies:
```
bun install
```
Start the server in development mode (with hot-reloading):
```
bun start:dev
```
The server will start listening at http://localhost:8080.
Run automated test suite:
```
bun test
```
Run load & memory benchmark test:
```
bun run test:load
```

Lint and auto-fix code style:

bun run lint      # check only
bun run lint:fix   # auto-fix

Build a standalone executable binary:
```
bun run build
./dist/podhound
```

Performance & Optimization Notes#

Password Hashing: Uses bcrypt (cost: 10) for minimal RAM overhead (~14 MB total server memory footprint).
Basic Auth Cache: In-memory caching with 5-minute TTL to bypass repeated password verification on high-frequency API calls.
Prepared Statements: Pre-compiled SQLite queries in service constructors to eliminate heap allocations per request.
Garbage Collection: Automatic background GC scheduled periodically via Bun.gc(true).

Project Structure#

src/
├── config/          # App configuration (env variables)
├── db/              # Database client, migrations
│   └── migrations/  # SQL migration files
├── routes/          # HTTP and CLI routing
│   ├── api/         # API sub-routers (auth, devices, subscriptions, episodes)
│   └── cli/         # CLI sub-routers (user management)
├── services/        # Business logic (auth, users, subscriptions, episodes)
├── types/           # Shared TypeScript interfaces
└── main.ts          # Application entry point

For a full list of available settings, please refer to the Environment Variables documentation.