testapi/README.md

POC Mock Task API

This folder contains a standalone mock API for a multi-organization task manager. It uses a local SQLite database file and comes pre-seeded with realistic mock data for organizations, users, projects, tasks, labels, and comments.

What It Includes

• Bun HTTP server with no external runtime dependencies
• local SQLite database file at data/mock-task-manager.sqlite
• deterministic seed data for three organizations
• task, project, user, and org summary endpoints
• write endpoints for creating tasks and updating task state
• a small test suite covering seeded reads and task mutations
• OpenAPI 3.0.0 document generated by tsoa controllers
• standalone Docker and Compose files for running the mock API by itself

Domain Model

The mock API is structured around a typical B2B task-management product:

• organizations: tenant records such as Acme Logistics and Northstar Health
• users: org-scoped staff members with roles and timezones
• projects: org-owned projects with an owner and delivery target
• tasks: work items linked to an org and project, optionally assigned to a user
• labels: org-scoped tags like backend, mobile, and compliance
• task_labels: many-to-many label assignments for tasks
• comments: task discussion entries authored by users

Seeded Data

The database is seeded with:

• 3 organizations
• 6 users
• 4 projects
• 7 tasks
• 4 labels
• 3 comments

The data is intentionally uneven across orgs so consumers can test:

• different organization sizes
• unassigned tasks
• blocked tasks
• urgent tasks
• org-specific filtering
• detail views with labels and threaded comments

API Surface

Health

• GET /health
• GET /openapi.json
• GET /swagger.json
• GET /api-docs

Organizations

• POST /orgs
• GET /orgs
• GET /orgs/:orgId
• GET /orgs/:orgId/projects
• GET /orgs/:orgId/tasks

Users and Projects

• POST /users
• GET /users
• GET /users?orgId=org_acme
• POST /projects
• GET /projects
• GET /projects?orgId=org_northstar

Tasks

• GET /tasks
• GET /tasks?orgId=org_acme&status=todo
• GET /tasks/:taskId
• POST /tasks
• PATCH /tasks/:taskId

Request Examples

Create a task:

curl -X POST http://localhost:3010/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_acme",
    "projectId": "proj_acme_ops",
    "assigneeUserId": "user_acme_2",
    "title": "Create export audit dashboard",
    "description": "Expose failed exports by warehouse and day.",
    "priority": "high",
    "storyPoints": 5,
    "dueDate": "2026-03-19"
  }'

Update a task:

curl -X PATCH http://localhost:3010/tasks/task_1001 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done",
    "assigneeUserId": null
  }'

How To Run

Seed the database file:

bun run db:seed

Start the server:

bun run start

Run in watch mode:

bun run dev

Run tests:

bun test

Regenerate tsoa routes and OpenAPI spec:

bun run generate:api

Run with Docker Compose from this folder:

docker compose up --build

Files That Matter

• src/index.ts: server startup and route dispatch
• src/controllers/*Controller.ts: all business endpoint contracts and handlers (tsoa decorators)
• src/generated/routes.ts: tsoa-generated Express route registration
• src/generated/swagger.json: tsoa-generated OpenAPI document
• src/openapi.ts: OpenAPI export used by the /openapi.json and /swagger.json endpoints
• src/database.ts: schema creation and seed data
• src/repository.ts: query and mutation helpers
• scripts/seed.ts: resets and reseeds the SQLite file
• tests/repository.test.ts: repository-level smoke coverage
• tests/api.test.ts: HTTP contract and OpenAPI coverage
• tests/routes.test.ts: verifies runtime business routes match the generated OpenAPI operations

What This Mock API Needs To Be Useful

For a task-manager mock API to actually help development, it needs more than one table and one endpoint. The important pieces are:

• tenant-aware data so frontend and backend code can test org-specific filters
• realistic relationships between orgs, users, projects, tasks, comments, and labels
• both list and detail endpoints, because dashboards and detail pages query differently
• mutable endpoints, so forms and optimistic updates can be tested
• predictable seed data, so demos and tests do not drift
• a local file-backed database, so the service is portable and disposable
• lightweight setup, so anyone can run it without standing up Postgres or external auth

Current Limitations

• no authentication or authorization layer
• no pagination
• no delete endpoints
• no file attachments or activity feed

Those are reasonable next additions if you want to use this mock API as part of the root compose stack.