docs(api): add API README

2026-01-29 21:29:50 -06:00
parent 48a643856f
commit 163a148c11
1 changed files with 254 additions and 0 deletions
--- a/apps/api/README.md
+++ b/apps/api/README.md
@@ -0,0 +1,254 @@
+# Mosaic Stack API
+
+The Mosaic Stack API is a NestJS-based backend service providing REST endpoints and WebSocket support for the Mosaic productivity platform.
+
+## Overview
+
+The API serves as the central backend for:
+- **Task Management** - Create, update, track tasks with filtering and sorting
+- **Event Management** - Calendar events and scheduling
+- **Project Management** - Organize work into projects
+- **Knowledge Base** - Wiki-style documentation with markdown support and wiki-linking
+- **Ideas** - Quick capture and organization of ideas
+- **Domains** - Categorize work across different domains
+- **Personalities** - AI personality configurations for the Ollama integration
+- **Widgets & Layouts** - Dashboard customization
+- **Activity Logging** - Track all user actions
+- **WebSocket Events** - Real-time updates for tasks, events, and projects
+
+## Available Modules
+
+| Module | Base Path | Description |
+|--------|-----------|-------------|
+| **Tasks** | `/api/tasks` | CRUD operations for tasks with filtering |
+| **Events** | `/api/events` | Calendar events and scheduling |
+| **Projects** | `/api/projects` | Project management |
+| **Knowledge** | `/api/knowledge/entries` | Wiki entries with markdown support |
+| **Knowledge Tags** | `/api/knowledge/tags` | Tag management for knowledge entries |
+| **Ideas** | `/api/ideas` | Quick capture and idea management |
+| **Domains** | `/api/domains` | Domain categorization |
+| **Personalities** | `/api/personalities` | AI personality configurations |
+| **Widgets** | `/api/widgets` | Dashboard widget data |
+| **Layouts** | `/api/layouts` | Dashboard layout configuration |
+| **Ollama** | `/api/ollama` | LLM integration (generate, chat, embed) |
+| **Users** | `/api/users/me/preferences` | User preferences |
+
+### Health Check
+
+- `GET /` - API health check
+- `GET /health` - Detailed health status including database connectivity
+
+## Authentication
+
+The API uses **BetterAuth** for authentication with the following features:
+
+### Authentication Flow
+
+1. **Email/Password** - Users can sign up and log in with email and password
+2. **Session Tokens** - BetterAuth generates session tokens with configurable expiration
+
+### Guards
+
+The API uses a layered guard system:
+
+| Guard | Purpose | Applies To |
+|-------|---------|------------|
+| **AuthGuard** | Verifies user authentication via Bearer token | Most protected endpoints |
+| **WorkspaceGuard** | Validates workspace membership and sets Row-Level Security (RLS) context | Workspace-scoped resources |
+| **PermissionGuard** | Enforces role-based access control | Admin operations |
+
+### Workspace Roles
+
+- **OWNER** - Full control over workspace
+- **ADMIN** - Administrative functions (can delete content, manage members)
+- **MEMBER** - Standard access (create/edit content)
+- **GUEST** - Read-only access
+
+### Permission Levels
+
+Used with `@RequirePermission()` decorator:
+
+```typescript
+Permission.WORKSPACE_OWNER   // Requires OWNER role
+Permission.WORKSPACE_ADMIN   // Requires ADMIN or OWNER
+Permission.WORKSPACE_MEMBER  // Requires MEMBER, ADMIN, or OWNER
+Permission.WORKSPACE_ANY     // Any authenticated member including GUEST
+```
+
+### Providing Workspace Context
+
+Workspace ID can be provided via:
+1. **Header**: `X-Workspace-Id: <workspace-id>` (highest priority)
+2. **URL Parameter**: `:workspaceId`
+3. **Request Body**: `workspaceId` field
+
+### Example: Protected Controller
+
+```typescript
+@Controller('tasks')
+@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
+export class TasksController {
+  @Post()
+  @RequirePermission(Permission.WORKSPACE_MEMBER)
+  async create(@Body() dto: CreateTaskDto, @Workspace() workspaceId: string) {
+    // workspaceId is verified and RLS context is set
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | API server port | `3001` |
+| `DATABASE_URL` | PostgreSQL connection string | Required |
+| `NODE_ENV` | Environment (`development`, `production`) | - |
+| `NEXT_PUBLIC_APP_URL` | Frontend application URL (for CORS) | `http://localhost:3000` |
+| `WEB_URL` | WebSocket CORS origin | `http://localhost:3000` |
+
+## Running Locally
+
+### Prerequisites
+
+- Node.js 18+
+- PostgreSQL database
+- pnpm workspace (part of Mosaic Stack monorepo)
+
+### Setup
+
+1. **Install dependencies:**
+   ```bash
+   pnpm install
+   ```
+
+2. **Set up environment variables:**
+   ```bash
+   cp .env.example .env  # If available
+   # Edit .env with your DATABASE_URL
+   ```
+
+3. **Generate Prisma client:**
+   ```bash
+   pnpm prisma:generate
+   ```
+
+4. **Run database migrations:**
+   ```bash
+   pnpm prisma:migrate
+   ```
+
+5. **Seed the database (optional):**
+   ```bash
+   pnpm prisma:seed
+   ```
+
+### Development
+
+```bash
+pnpm dev
+```
+
+The API will start on `http://localhost:3001`
+
+### Production Build
+
+```bash
+pnpm build
+pnpm start:prod
+```
+
+### Database Management
+
+```bash
+# Open Prisma Studio
+pnpm prisma:studio
+
+# Reset database (dev only)
+pnpm prisma:reset
+
+# Run migrations in production
+pnpm prisma:migrate:prod
+```
+
+## API Documentation
+
+The API does not currently include Swagger/OpenAPI documentation. Instead:
+
+- **Controller files** contain detailed JSDoc comments describing each endpoint
+- **DTO classes** define request/response schemas with class-validator decorators
+- Refer to the controller source files in `src/` for endpoint details
+
+### Example: Reading an Endpoint
+
+```typescript
+// src/tasks/tasks.controller.ts
+
+/**
+ * POST /api/tasks
+ * Create a new task
+ * Requires: MEMBER role or higher
+ */
+@Post()
+@RequirePermission(Permission.WORKSPACE_MEMBER)
+async create(@Body() createTaskDto: CreateTaskDto, @Workspace() workspaceId: string) {
+  return this.tasksService.create(workspaceId, user.id, createTaskDto);
+}
+```
+
+## WebSocket Support
+
+The API provides real-time updates via WebSocket. Clients receive notifications for:
+
+- `task:created` - New task created
+- `task:updated` - Task modified
+- `task:deleted` - Task removed
+- `event:created` - New event created
+- `event:updated` - Event modified
+- `event:deleted` - Event removed
+- `project:updated` - Project modified
+
+Clients join workspace-specific rooms for scoped updates.
+
+## Testing
+
+```bash
+# Run unit tests
+pnpm test
+
+# Run tests with coverage
+pnpm test:coverage
+
+# Run e2e tests
+pnpm test:e2e
+
+# Watch mode
+pnpm test:watch
+```
+
+## Project Structure
+
+```
+src/
+├── activity/          # Activity logging
+├── auth/              # Authentication (BetterAuth config, guards)
+├── common/            # Shared decorators and guards
+├── database/          # Database module
+├── domains/           # Domain management
+├── events/            # Event management
+├── filters/           # Global exception filters
+├── ideas/             # Idea capture and management
+├── knowledge/         # Knowledge base (entries, tags, markdown)
+├── layouts/           # Dashboard layouts
+├── lib/               # Utility functions
+├── ollama/            # LLM integration
+├── personalities/     # AI personality configurations
+├── prisma/            # Prisma service
+├── projects/          # Project management
+├── tasks/             # Task management
+├── users/             # User preferences
+├── widgets/           # Dashboard widgets
+├── websocket/         # WebSocket gateway
+├── app.controller.ts  # Root controller (health check)
+├── app.module.ts      # Root module
+└── main.ts            # Application bootstrap
+```