mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: Restructure documentation with Bookstack-compatible hierarchy

Browse Source 
- Organized docs into numbered shelf/book/chapter/page structure
- Created comprehensive README.md with project overview
- Added Getting Started book (quick start, installation, configuration)
- Added Development book (workflow, testing, type sharing)
- Added Architecture book (design principles, PDA-friendly patterns)
- Added API Reference book (conventions, authentication)
- Moved TYPE-SHARING.md to proper location
- Updated all cross-references in main README
- Created docs/README.md as master index
- Removed old QA automation reports
- Removed deprecated SETUP.md (content split into new structure)

Documentation structure follows Bookstack best practices:
- Numbered books: 1-getting-started, 2-development, 3-architecture, 4-api
- Numbered chapters and pages for ordering
- Clear hierarchy and navigation
- Cross-referenced throughout

Complete documentation available at: docs/README.md

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
2026-01-28 17:46:33 -06:00
parent 6a038d093b
commit dd5b3117a7
18 changed files with 3846 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

319
docs/4-api/1-conventions/1-endpoints.md Normal file
View File

@@ -0,0 +1,319 @@
# API Endpoint Conventions
Standard patterns for all Mosaic Stack API endpoints.
## Base URL
- **Development:** `http://localhost:3001`
- **Production:** `https://api.example.com`
## Standard REST Endpoints
```
GET /api/{resource} # List resources (with pagination)
GET /api/{resource}/:id # Get single resource
POST /api/{resource} # Create new resource
PATCH /api/{resource}/:id # Update resource (partial)
PUT /api/{resource}/:id # Replace resource (full)
DELETE /api/{resource}/:id # Delete resource
```
## Response Format
### Success Response
```json
{
"data": {
"id": "uuid",
"name": "Example",
"createdAt": "2026-01-28T12:00:00.000Z"
}
}
```
### List Response (with pagination)
```json
{
"data": [
{ "id": "1", "name": "Item 1" },
{ "id": "2", "name": "Item 2" }
],
"meta": {
"total": 50,
"page": 1,
"limit": 10,
"totalPages": 5
}
}
```
### Error Response
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": {
"email": "Invalid email format"
}
}
}
```
## HTTP Status Codes
| Code | Meaning | Usage |
|------|---------|-------|
| 200 | OK | Successful GET, PATCH, PUT |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Invalid input |
| 401 | Unauthorized | Missing/invalid auth token |
| 403 | Forbidden | Valid token, insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Resource already exists |
| 422 | Unprocessable Entity | Validation failed |
| 500 | Internal Server Error | Server error |
## Pagination
All list endpoints support pagination via query parameters:
```
GET /api/tasks?page=1&limit=20
```
**Parameters:**
- `page` — Page number (default: 1)
- `limit` — Items per page (default: 10, max: 100)
**Response includes:**
```json
{
"data": [...],
"meta": {
"total": 150,
"page": 1,
"limit": 20,
"totalPages": 8
}
}
```
## Filtering
Use query parameters for filtering:
```
GET /api/tasks?status=active&priority=high
GET /api/events?start_date=2026-01-01&end_date=2026-01-31
```
**Supported operators:**
- `=` — Equals
- `_gt` — Greater than (e.g., `created_at_gt=2026-01-01`)
- `_lt` — Less than
- `_gte` — Greater than or equal
- `_lte` — Less than or equal
- `_in` — In array (e.g., `status_in=active,pending`)
## Sorting
Use `sort` parameter:
```
GET /api/tasks?sort=created_at # Ascending
GET /api/tasks?sort=-created_at # Descending (minus prefix)
GET /api/tasks?sort=-priority,created_at # Multiple fields
```
## Field Selection
Request specific fields to reduce payload size:
```
GET /api/tasks?fields=id,title,status
```
**Response:**
```json
{
"data": [
{ "id": "1", "title": "Task 1", "status": "active" }
]
}
```
## Relationships
Include related resources:
```
GET /api/tasks?include=assignee,project
```
**Response:**
```json
{
"data": {
"id": "1",
"title": "Task 1",
"assignee": {
"id": "user-1",
"name": "John Doe"
},
"project": {
"id": "proj-1",
"name": "Project Alpha"
}
}
}
```
## Authentication
All authenticated endpoints require Bearer token:
```http
Authorization: Bearer {session_token}
```
See [Authentication Endpoints](../2-authentication/1-endpoints.md) for details.
## Request Headers
**Required:**
```http
Content-Type: application/json
```
**Optional:**
```http
Authorization: Bearer {token}
X-Workspace-ID: {workspace-uuid} # For multi-tenant requests
```
## Validation Errors
Validation errors return 422 with detailed field errors:
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Input validation failed",
"details": {
"email": "Invalid email format",
"password": "Must be at least 8 characters"
}
}
}
```
## Rate Limiting
API endpoints are rate-limited:
- **Anonymous:** 60 requests/hour
- **Authenticated:** 1000 requests/hour
**Rate limit headers:**
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1643723400
```
When exceeded, returns 429 Too Many Requests.
## CORS
CORS is configured for frontend origin:
```javascript
// Allowed origins
const origins = [
process.env.NEXT_PUBLIC_APP_URL,
'http://localhost:3000',
'http://localhost:3001'
];
```
## Versioning
Currently v1 (implicit). Future versions will use URL versioning:
```
/api/v2/tasks
```
## Health Check
```
GET /health
```
**Response:**
```json
{
"status": "ok",
"timestamp": "2026-01-28T12:00:00.000Z",
"uptime": 123456
}
```
## Examples
### Create Task
```bash
curl -X POST http://localhost:3001/api/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
"title": "Complete API documentation",
"description": "Write comprehensive API docs",
"priority": "high",
"targetDate": "2026-01-30"
}'
```
**Response (201):**
```json
{
"data": {
"id": "task-uuid",
"title": "Complete API documentation",
"status": "pending",
"priority": "high",
"createdAt": "2026-01-28T12:00:00.000Z"
}
}
```
### List Tasks with Filters
```bash
curl "http://localhost:3001/api/tasks?status=active&sort=-created_at&limit=5" \
-H "Authorization: Bearer {token}"
```
### Update Task
```bash
curl -X PATCH http://localhost:3001/api/tasks/task-uuid \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
"status": "completed"
}'
```
## Next Steps
- **Authentication** — [Authentication Endpoints](../2-authentication/1-endpoints.md)
- **Type Definitions** — [API Types](../2-authentication/2-types.md)
- **Implementation** — [Development Workflow](../../2-development/1-workflow/1-branching.md)