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