# 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

- `GET /orgs`
- `GET /orgs/:orgId`
- `GET /orgs/:orgId/projects`
- `GET /orgs/:orgId/tasks`

### Users and Projects

- `GET /users`
- `GET /users?orgId=org_acme`
- `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:

```bash
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:

```bash
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:

```bash
bun run db:seed
```

Start the server:

```bash
bun run start
```

Run in watch mode:

```bash
bun run dev
```

Run tests:

```bash
bun test
```

Regenerate tsoa routes and OpenAPI spec:

```bash
bun run generate:api
```

Run with Docker Compose from this folder:

```bash
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.
