stack/apps/api/README.md

# 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
```