AI Lab Event Platform Backend

Backend foundation for the AI innovation competition platform. The project is set up for Bun + Hono + Effect + Prisma and follows the data model in agent-refs/final-data-model-and-tables.md.

Current Status

Implemented backend capabilities:

• Hono app composition with request context, secure headers, CORS, observability, JSON error handling, and Prisma context middleware.
• PostgreSQL data model with Prisma 7 and @prisma/adapter-pg.
• Seed data for roles, permissions, tracks, submission types, teams, accounts, projects, submissions, reviews, analytics events, and system settings.
• Auth and account flows:
  • email/password login
  • one-time password change
  • team application creation
  • admin approval for team applications
  • reviewer creation
  • account password reset
  • account update
• Project read APIs:
  • project cards list
  • project detail
• OpenAPI and docs:
  • generated OpenAPI 3.1 document
  • Scalar API reference UI
• Test coverage:
  • default Bun tests
  • opt-in real PostgreSQL integration tests with isolated schemas

Recommended next product iteration: implement project draft/submission and “my submissions” APIs, then review workflows. See docs/progress-report-2026-04-29.md.

Stack

• Runtime/package manager: Bun
• HTTP framework: Hono
• Typed effects/config/schema: Effect (Config, Effect, Schema)
• Database ORM: Prisma 7 with PostgreSQL and @prisma/adapter-pg
• API documentation: hono-openapi + @scalar/hono-api-reference

Layout

src/
  app.ts                         Hono composition root
  index.ts                       Bun server entry
  config/env.ts                  Effect Config-based environment loading
  db/prisma.ts                   Prisma client factory
  domain/catalog.ts              Business const-object dictionaries
  domain/schemas.ts              Effect Schema DTO/entity definitions
  http/
    middleware/                  request id, observability, Prisma context, error handling
    openapi.ts                   shared OpenAPI response helpers
    prisma.ts                    request Prisma requirement helper
    types.ts                     Hono app env and API envelope types
    validation/effect-schema.ts  hono-openapi validator bridge for Effect Schema
  modules/
    admin/                       admin account and team-application routes
    auth/                        login, password, token, team-application routes
    docs/                        /openapi.json and Scalar UI routes
    health/                      health endpoint
    projects/                    project list/detail APIs + repository
  shared/                        typed errors and Effect helpers
prisma/
  schema.prisma                  PostgreSQL data model
  seed.ts                        idempotent seed data
tests/
  integration/                   opt-in real database integration tests
  modules/                       route/module tests
  support/                       test helpers
docs/
  progress-report-2026-04-29.md  PRD/progress/next-iteration report
agent-refs/
  *.md                           PRD, UI/UX, and data-model references

Data-model note

The volatile dictionaries AwardStage, AssetType, and AnalyticsEventType are intentionally not PostgreSQL/Prisma enums. They are stored as strings in the database and constrained at the business/API layer with const objects and Effect Schema:

• src/domain/catalog.ts
• src/domain/schemas.ts

This keeps database migrations stable when product terminology changes, while still preserving TypeScript and runtime validation.

Setup

bun install
cp .env.example .env
bun run db:generate
bun run db:validate

Set DATABASE_URL to a PostgreSQL connection string and set a high-entropy AUTH_SECRET with at least 32 characters.

To initialize local development data, set seed passwords in .env:

SEED_ADMIN_PASSWORD=...
SEED_REVIEWER_PASSWORD=...
SEED_CONTESTANT_PASSWORD=...

Then run:

bun run db:push
bun run db:seed

The development seed creates baseline roles, permissions, tracks, settings, 3 submission types, 30 teams, 30 contestant projects, 26 submitted snapshots, 5 reviewers, reviews, and analytics rows for local validation.

For deployment bootstrap data, set only SEED_ADMIN_PASSWORD and run:

bun run db:seed:deploy

The deploy seed creates only the admin account plus baseline roles, permissions, tracks, submission types, and settings.

Development

bun run dev

Default URL: http://localhost:3000

Useful endpoints:

• GET / — small JSON index with health/docs links
• GET /api/health
• POST /api/auth/login
• POST /api/auth/change-password
• POST /api/auth/team-applications
• POST /api/admin/team-applications/:id/approve
• POST /api/admin/reviewers
• POST /api/admin/accounts/:id/reset-password
• PATCH /api/admin/accounts/:id
• GET /api/projects?limit=20
• GET /api/projects/:id
• GET /openapi.json
• GET /docs and GET /docs/
• GET /scalar and GET /scalar/

API Documentation

OpenAPI is generated from route-local metadata and validators:

• Add describeRoute(...) directly to each endpoint.
• Use effectValidator(...) for params/query/body so hono-openapi can generate input schemas.
• Do not maintain a separate duplicated OpenAPI route registry.

Documentation UI:

/openapi.json  machine-readable OpenAPI 3.1 document
/docs          Scalar API Reference UI
/docs/         same UI, no redirect
/scalar        same UI, no redirect
/scalar/       same UI, no redirect

Scripts

• bun run dev — hot-reload server
• bun run start — run server
• bun run typecheck — TypeScript validation
• bun run lint / bun run lint:fix — ESLint
• bun test — default Bun tests; real DB integration tests are skipped by default
• bun run test:integration:db — opt-in real PostgreSQL integration tests using isolated ai_lab_it_* schemas
• bun run db:generate — generate Prisma client
• bun run db:validate — validate Prisma schema
• bun run db:push — push schema to development DB
• bun run db:migrate — create/apply Prisma migration
• bun run db:seed — seed local development data with 30 teams/projects, submitted snapshots, reviews, analytics, and baseline settings
• bun run db:seed:deploy — seed deploy bootstrap data only: admin account plus baseline roles, permissions, tracks, submission types, and settings
• bun run db:studio — open Prisma Studio

Testing

Default verification before handoff:

bun run typecheck
bun run lint
bun test

Run database-backed integration tests when changing Prisma-backed behavior:

bun run test:integration:db

Integration-test safety behavior:

• Requires NODE_ENV=test.
• Requires RUN_DATABASE_INTEGRATION_TESTS=1.
• Refuses production-looking DATABASE_URL names.
• Creates a temporary isolated schema named ai_lab_it_*.
• Drops only that isolated schema after the run.
• Does not reset or truncate public.
• Does not print secrets.

Security & Configuration

Never commit .env. Required operational secrets/config include:

• DATABASE_URL
• AUTH_SECRET — minimum 32 characters
• SEED_ADMIN_PASSWORD — for db:seed and db:seed:deploy
• SEED_REVIEWER_PASSWORD — for local development db:seed
• SEED_CONTESTANT_PASSWORD — for local development db:seed

Treat seed credentials and the current auth setup as development/test-oriented until production authentication, deployment, and secret-management hardening are explicitly implemented.