development

prerequisites#

• node.js >= 20
• pnpm >= 9
• redis (for task queue)
• git >= 2.20

tech stack#

project structure#

apps/server/src/
├── auth/           # jwt auth, passport, guards, decorators
├── common/         # crypto service, rate limiter, logger
├── database/       # DatabaseService, MigrationRunner, repositories
├── dispatcher/     # task lifecycle, scheduler, worker connections
├── notifier/       # notifications (in-app, lark/slack)
├── redis/          # redis service wrapper
├── web/            # http controllers + admin/
└── main.ts

apps/web/src/
├── components/     # reusable ui components
├── pages/          # route pages (admin/, docs/)
├── services/       # api client (ky), websocket client
├── store/          # zustand stores
├── i18n/           # internationalization
└── App.tsx

npm scripts#

database#

sqlite with wal mode. the database file lives at ~/.overlord/data/overlord.db (or .data/ in development, which is gitignored).

migrations are in database/migrations/ and run automatically on server start. they are numbered sequentially (e.g., 001-initial.sql, 002-add-audit-logs.sql).

protocol package#

the packages/protocol package contains all shared types, enums, websocket frame definitions, and constants used by both server and clients.

after modifying types:

pnpm --filter @overlordai/protocol build

coding conventions#

• use rounded-[4px] not rounded-md for border radius
• all ui text is lowercase by default (css text-transform: lowercase)
• font: jetbrains mono throughout
• never return passwordHash or totpSecret in api responses
• do not inherit process.env in worker pty sessions
• use ky for http requests (not axios/fetch)
• use vitest for testing (not jest)

role-based access control#