Platform Backend

The platform backend (apps/platform-backend) owns the database, exposes the REST API, dispatches workers, processes inbound webhooks, runs the claw scheduler, and bridges Slack threads to agent sessions.

Stack

• Runtime: Node.js 24+, TypeScript 5.3.
• Framework: Express 4 with Helmet, express-rate-limit, cors, Multer (uploads), Joi (validation), and Passport (passport-local + a custom strategy).
• Database: PostgreSQL via Kysely 0.27 (typed query builder). Migrations live in src/migrations/ (numbered 001–056+).
• Auth: session-based, with user_sessions rows and a configurable AUTH_ENABLED env switch for local development.
• AWS: SDK v3 clients for ECS, Lambda, S3, SSM, CloudWatch.
• Logging: Winston with winston-daily-rotate-file. JSON-structured to make CloudWatch ingestion straightforward.
• Slack: @chat-adapter/slack 4.22 with @chat-adapter/state-pg 4.22 for persistent thread state.
• Scheduling: node-cron for the in-process claw scheduler.

Database access

All persistence goes through Kysely. Each domain has a DAO that exposes a small surface (get, list, create, update, delete) and a few specialised queries. There is no ORM, no entity mapping, and no implicit lazy loading — you write the SQL through the type-safe builder, and the table types in src/persistence/types/database.ts are kept in sync with migrations.

Migrations are numbered (001_create_users.ts, 035_add_ticket_workflow_phase.ts, 043_add_claw_tables.ts, etc.) and run automatically on backend startup. They can also be run manually with npm run migrate:latest or rolled back with npm run migrate:down.

Job orchestration

When work needs to happen, the backend prepares it, sends it to a worker, and keeps track of progress.

1. The system gathers the information needed for the task.
2. It marks the task as queued.
3. It sends the task to the appropriate worker.
4. The worker reports back as it makes progress.
5. When finished, the backend updates the ticket and stores the result.

The backend also keeps a history of changes so work can be reviewed later.

Approvals

Some parts of the work need approval before they continue. The backend tracks whether something is waiting, approved, or rejected, and records who made the decision.

If a step needs approval, it will not continue until that approval is given or an override is allowed.

Webhooks

The backend listens for updates from other tools and turns them into changes in the system.

This includes:

• GitHub updates
• Jira updates
• Shortcut updates
• Custom incoming updates

Every incoming update is recorded so it can be reviewed if needed.

Slack chat backend

Slack messages can be connected to work in the system. This lets people start work, reply to it, and keep the conversation tied to the right task.

The Slack bridge keeps messages in sync so the conversation continues even if the system restarts.

Local development

To run the full app locally, start the services with Docker Compose.

You’ll need to set a few environment variables first, including database settings and the keys used for local development.

For production setup details, see Secrets Management.