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

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

Recommended for quick setup and production deployments.

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

# Copy and configure environment
cp .env.example .env
# Edit .env with your settings

# Start core services (PostgreSQL, Valkey, API, Web)
docker compose up -d

# Or start with optional services
docker compose --profile full up -d  # Includes Authentik and Ollama

# View logs
docker compose logs -f

# Check service status
docker compose ps

# Access services
# Web:  http://localhost:3000
# API:  http://localhost:3001
# Auth: http://localhost:9000 (if Authentik enabled)

# Stop services
docker compose down

What's included:

• PostgreSQL 17 with pgvector extension
• Valkey (Redis-compatible cache)
• Mosaic API (NestJS)
• Mosaic Web (Next.js)
• Authentik OIDC (optional, use --profile authentik)
• Ollama AI (optional, use --profile ollama)

See Docker Deployment Guide for complete documentation.

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 ✅ COMPLETED
• Issue #7: Activity logging system (planned)
• Issue #8: Docker compose setup ✅ COMPLETED

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

# 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

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

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

Authorization: Bearer {session_token}

See API Reference for complete API documentation.

Configuration

Key environment variables:

# 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 for all configuration options.

Type Sharing

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

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 for the complete type sharing strategy.

Contributing

1. Check the issue tracker 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 — Get running in 5 minutes
• Installation — Prerequisites, local setup, Docker deployment
• Configuration — Environment variables and Authentik OIDC

💻 Development

• Workflow — Branching strategy, testing requirements, commit guidelines
• Database — Schema design, migrations, Prisma usage
• Type Sharing — Shared types across monorepo

🏗️ Architecture

• Overview — System design and components
• Authentication — BetterAuth and OIDC integration
• Design Principles — PDA-friendly patterns (non-negotiable)

🔌 API Reference

• Conventions — REST patterns, pagination, filtering
• Authentication — Auth endpoints and flows

Browse all documentation: 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.