stack/README.md

# Mosaic Stack

Multi-tenant personal assistant platform with PostgreSQL backend, Authentik SSO, and MoltBot integration.

## Overview

Mosaic Stack is a modern, PDA-friendly platform designed to help users manage their personal and professional lives with:

- **Multi-user workspaces** with team collaboration
- **Task management** with flexible organization
- **Event & calendar** integration
- **Project tracking** with Gantt charts and Kanban boards
- **MoltBot integration** for natural language interactions
- **Authentik OIDC** for secure, enterprise-grade authentication

**Version:** 0.0.1 (Pre-MVP)
**Repository:** https://git.mosaicstack.dev/mosaic/stack

## Technology Stack

| Layer | Technology |
|-------|------------|
| **Frontend** | Next.js 16 + React + TailwindCSS + Shadcn/ui |
| **Backend** | NestJS + Prisma ORM |
| **Database** | PostgreSQL 17 + pgvector |
| **Cache** | Valkey (Redis-compatible) |
| **Auth** | Authentik (OIDC) via BetterAuth |
| **AI** | Ollama (local or remote) |
| **Messaging** | MoltBot (stock + plugins) |
| **Real-time** | WebSockets (Socket.io) |
| **Monorepo** | pnpm workspaces + TurboRepo |
| **Testing** | Vitest + Playwright |
| **Deployment** | Docker + docker-compose |

## Quick Start

### Prerequisites

- Node.js 20+ and pnpm 9+
- PostgreSQL 17+ (or use Docker)
- Docker & Docker Compose (optional, for turnkey deployment)

### Installation

```bash
# Clone the repository
git clone https://git.mosaicstack.dev/mosaic/stack mosaic-stack
cd mosaic-stack

# Install dependencies
pnpm install

# Copy environment file
cp .env.example .env

# Configure environment variables (see CONFIGURATION.md)
# Edit .env with your database and auth settings

# Generate Prisma client
pnpm prisma:generate

# Run database migrations
pnpm prisma:migrate

# Seed development data (optional)
pnpm prisma:seed

# Start development servers
pnpm dev
```

### Docker Deployment (Turnkey)

```bash
# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down
```

See [Installation Guide](docs/1-getting-started/2-installation/) for detailed installation instructions.

## Project Structure

```
mosaic-stack/
├── apps/
│   ├── api/                      # NestJS backend API
│   │   ├── src/
│   │   │   ├── auth/             # BetterAuth + Authentik OIDC
│   │   │   ├── prisma/           # Database service
│   │   │   └── app.module.ts     # Main application module
│   │   ├── prisma/
│   │   │   └── schema.prisma     # Database schema
│   │   └── Dockerfile
│   └── web/                      # Next.js 16 frontend (planned)
│       ├── app/
│       ├── components/
│       └── Dockerfile
├── packages/
│   ├── shared/                   # Shared types & utilities
│   │   └── src/types/
│   │       ├── auth.types.ts     # Auth types (AuthUser, Session, etc.)
│   │       ├── database.types.ts # DB entity types
│   │       └── enums.ts          # Shared enums
│   ├── ui/                       # Shared UI components (planned)
│   └── config/                   # Shared configuration (planned)
├── plugins/                      # MoltBot skills (planned)
│   ├── mosaic-plugin-brain/      # API query skill
│   ├── mosaic-plugin-calendar/   # Calendar skill
│   └── mosaic-plugin-tasks/      # Task management skill
├── docker/
│   ├── docker-compose.yml        # Production deployment
│   └── init-scripts/             # PostgreSQL initialization
├── docs/
│   ├── SETUP.md                  # Installation guide
│   ├── CONFIGURATION.md          # Environment configuration
│   ├── DESIGN-PRINCIPLES.md      # PDA-friendly design patterns
│   ├── API.md                    # API documentation
│   ├── TYPE-SHARING.md           # Type sharing strategy
│   └── scratchpads/              # Development notes
├── .env.example                  # Environment template
├── turbo.json                    # TurboRepo configuration
└── pnpm-workspace.yaml           # Workspace configuration
```

## Current Implementation Status

### ✅ Completed (v0.0.1)

- **Issue #1:** Project scaffold and monorepo setup
- **Issue #2:** PostgreSQL 17 + pgvector database schema
- **Issue #3:** Prisma ORM integration with tests and seed data
- **Issue #4:** Authentik OIDC authentication with BetterAuth

**Test Coverage:** 26/26 tests passing (100%)

### 🚧 In Progress (v0.0.x)

- **Issue #5:** Multi-tenant workspace isolation (planned)
- **Issue #6:** Frontend authentication UI (planned)
- **Issue #7:** Task management API & UI (planned)

### 📋 Planned Features (v0.1.0 MVP)

- Event/calendar management
- Project tracking with Gantt charts
- MoltBot integration
- WebSocket real-time updates
- Data migration from jarvis-brain

See the [issue tracker](https://git.mosaicstack.dev/mosaic/stack/issues) for complete roadmap.

## Development Workflow

### Branch Strategy

- `main` — Stable releases only
- `develop` — Active development (default working branch)
- `feature/*` — Feature branches from develop
- `fix/*` — Bug fix branches

### Running Locally

```bash
# Start all services (requires Docker for PostgreSQL)
pnpm dev              # All apps

# Or run individually
pnpm dev:api          # API only (http://localhost:3001)
pnpm dev:web          # Web only (http://localhost:3000)

# Database tools
pnpm prisma:studio    # Open Prisma Studio
pnpm prisma:migrate   # Run migrations
pnpm prisma:generate  # Regenerate Prisma client
```

### Testing

```bash
pnpm test             # All tests
pnpm test:api         # API tests only
pnpm test:web         # Web tests only
pnpm test:e2e         # E2E tests with Playwright
pnpm test:coverage    # Generate coverage report
```

### Building

```bash
pnpm build            # Build all apps
pnpm build:api        # Build API only
pnpm build:web        # Build web only
```

## Design Philosophy

Mosaic Stack follows strict **PDA-friendly design principles**:

### Language Guidelines

We **never** use demanding or stressful language:

| ❌ NEVER | ✅ ALWAYS |
|----------|-----------|
| OVERDUE | Target passed |
| URGENT | Approaching target |
| MUST DO | Scheduled for |
| CRITICAL | High priority |
| YOU NEED TO | Consider / Option to |
| REQUIRED | Recommended |

### Visual Principles

- **10-second scannability** — Key info visible immediately
- **Visual chunking** — Clear sections with headers
- **Single-line items** — Compact, scannable lists
- **Calm colors** — No aggressive reds for status indicators
- **Progressive disclosure** — Details on click, not upfront

See [Design Principles](docs/3-architecture/3-design-principles/1-pda-friendly.md) for complete guidelines.

## API Conventions

### Endpoints

```
GET    /api/{resource}           # List (with pagination, filters)
GET    /api/{resource}/:id       # Get single item
POST   /api/{resource}           # Create new item
PATCH  /api/{resource}/:id       # Update item
DELETE /api/{resource}/:id       # Delete item
```

### Authentication

All authenticated endpoints require a Bearer token:

```http
Authorization: Bearer {session_token}
```

See [API Reference](docs/4-api/) for complete API documentation.

## Configuration

Key environment variables:

```bash
# Database
DATABASE_URL=postgresql://mosaic:password@localhost:5432/mosaic

# Authentik OIDC
OIDC_ISSUER=https://auth.example.com/application/o/mosaic-stack/
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret

# JWT Session
JWT_SECRET=change-this-to-a-random-secret-in-production
JWT_EXPIRATION=24h

# Application
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

See [Configuration](docs/1-getting-started/3-configuration/1-environment.md) for all configuration options.

## Type Sharing

Types used by both frontend and backend live in `@mosaic/shared`:

```typescript
import type { AuthUser, Task, Event } from "@mosaic/shared";

// Frontend
function UserProfile({ user }: { user: AuthUser }) {
  return <div>{user.name}</div>;
}

// Backend
@Get("profile")
@UseGuards(AuthGuard)
getProfile(@CurrentUser() user: AuthUser) {
  return user;
}
```

See [Type Sharing Strategy](docs/2-development/3-type-sharing/1-strategy.md) for the complete type sharing strategy.

## Contributing

1. Check the [issue tracker](https://git.mosaicstack.dev/mosaic/stack/issues) for open issues
2. Create a feature branch: `git checkout -b feature/my-feature develop`
3. Make your changes with tests (minimum 85% coverage required)
4. Run tests: `pnpm test`
5. Build: `pnpm build`
6. Commit with conventional format: `feat(#issue): Description`
7. Push and create a pull request to `develop`

### Commit Format

```
<type>(#issue): Brief description

Detailed explanation if needed.

Fixes #123
```

**Types:** `feat`, `fix`, `docs`, `test`, `refactor`, `chore`

## Testing Requirements

- **Minimum 85% coverage** for new code
- **TDD approach** — Write tests before implementation
- **All tests pass** before PR merge
- Use Vitest for unit/integration tests
- Use Playwright for E2E tests

## Documentation

Complete documentation is organized in a Bookstack-compatible structure in the `docs/` directory.

### 📚 Getting Started

- **[Quick Start](docs/1-getting-started/1-quick-start/1-overview.md)** — Get running in 5 minutes
- **[Installation](docs/1-getting-started/2-installation/)** — Prerequisites, local setup, Docker deployment
- **[Configuration](docs/1-getting-started/3-configuration/)** — Environment variables and Authentik OIDC

### 💻 Development

- **[Workflow](docs/2-development/1-workflow/)** — Branching strategy, testing requirements, commit guidelines
- **[Database](docs/2-development/2-database/)** — Schema design, migrations, Prisma usage
- **[Type Sharing](docs/2-development/3-type-sharing/1-strategy.md)** — Shared types across monorepo

### 🏗️ Architecture

- **[Overview](docs/3-architecture/1-overview/)** — System design and components
- **[Authentication](docs/3-architecture/2-authentication/)** — BetterAuth and OIDC integration
- **[Design Principles](docs/3-architecture/3-design-principles/1-pda-friendly.md)** — PDA-friendly patterns (non-negotiable)

### 🔌 API Reference

- **[Conventions](docs/4-api/1-conventions/1-endpoints.md)** — REST patterns, pagination, filtering
- **[Authentication](docs/4-api/2-authentication/1-endpoints.md)** — Auth endpoints and flows

**Browse all documentation:** [docs/](docs/)

## Related Projects

- **jarvis-brain** — Original JSON-based personal assistant (migration source)
- **MoltBot** — Stock messaging gateway for multi-platform integration

## Security

- **Session-based authentication** with secure JWT tokens
- **Row-level security** ready for multi-tenant isolation
- **OIDC integration** with Authentik for enterprise SSO
- **Secure error handling** — No sensitive data in logs or responses
- **Type-safe validation** — TypeScript catches issues at compile time

## License

[Add license information]

## Support

- **Issues:** https://git.mosaicstack.dev/mosaic/stack/issues
- **Documentation:** https://git.mosaicstack.dev/mosaic/stack/wiki

---

**Mosaic Stack v0.0.1** — Building the future of personal assistants.