184 lines
4.8 KiB
Markdown
184 lines
4.8 KiB
Markdown
# 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:
|
|
|
|
```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.
|