added repo
This commit is contained in:
170
README.md
Normal file
170
README.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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.1 document endpoints for import tooling
|
||||
- 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
|
||||
```
|
||||
|
||||
Run with Docker Compose from this folder:
|
||||
|
||||
```bash
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
## Files That Matter
|
||||
|
||||
- `src/index.ts`: HTTP routes and server startup
|
||||
- `src/openapi.ts`: importable OpenAPI 3.1 document
|
||||
- `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
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user