Architecture Overview

LearnHouse is a multi-directory project with multiple applications that work together to deliver the full platform experience. The system follows a clear separation of concerns between the frontend, backend, and supporting services.

Project Structure

learnhouse/
├── apps/
│   ├── web/      # Next.js frontend
│   ├── api/      # FastAPI backend
│   ├── collab/   # Hocuspocus collaboration server
│   └── cli/      # LearnHouse CLI
├── docker/       # Production Dockerfile helpers (nginx config, start.sh)
└── Dockerfile    # Monolithic image used by the CLI setup wizard

Self-hosted deployments do not have a checked-in docker-compose.yml. The LearnHouse CLI (apps/cli) generates docker-compose.yml, .env, and reverse proxy config at setup time from the templates in apps/cli/src/templates/.

How It All Fits Together

The platform consists of four applications backed by two core services:

• Web (Next.js) — The user-facing frontend that communicates with the backend API and the collaboration server.
• API (FastAPI) — The backend that handles authentication, course management, storage, uploads, AI features, and all business logic.
• Collab (Hocuspocus) — A WebSocket server that powers real-time collaborative editing with JWT authentication, Redis persistence, and per-board user limits.
• CLI (Commander) — A command-line tool used for local development and management tasks.

Backing Services

LearnHouse relies on two primary backing services:

• PostgreSQL 16 (pgvector) — The primary relational database for storing all application data including users, courses, organizations, and activity records. Uses the pgvector extension for AI embedding storage. Both dev and self-host production use the pgvector/pgvector:pg16 image.
• Redis — Used for caching, session management, collaboration state persistence, and message brokering between services. Dev mode uses redis:8.6.1-alpine; the CLI-generated self-host production stack uses redis:7.2.3-alpine.