Overlook Portal Template

⚠️ TEMPLATE REPO — DO NOT COMMIT CLIENT WORK HERE This is the template. Per-client work lives in overlook-portal-{clientslug} repos. If you see this banner in a client repo, the setup script didn't run — STOP and investigate before committing anything.

A reusable client portal scaffold for Overlook Strategy and partners.

Each new client gets their own repo created from this template (via the GitHub "Use this template" button), their own Vercel project, their own Railway project + Postgres, and their own Sentry projects. Nothing is shared at the code level — physical isolation prevents cross-client contamination.

Stack

• Frontend: Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS 4, pnpm
• Backend: FastAPI (Python 3.12), SQLAlchemy 2.0 async, Alembic
• Database: PostgreSQL 16 + pgvector extension
• AI (optional, default off): pluggable provider — Gemini (recommended), Groq, or Ollama
• Optional integrations: Notion CMS, Sentry, Google Drive
• Deploy: Vercel (frontend) + Railway (backend + Postgres)

See CLAUDE.md for design decisions, coding rules, and gotchas.

Quick start (per-client deployment)

1. Click "Use this template" on GitHub → name the new repo overlook-portal-{clientslug}
2. Clone locally to ~/code/overlook-portal-{clientslug}/
3. Provision Railway (project, Postgres, pgvector, Volume) — see SETUP.md
4. Generate secrets: openssl rand -hex 32 (for ADMIN_API_KEY and SESSION_SECRET)
5. Copy .env.example files and fill in values
6. Run bash scripts/setup.sh — installs deps, runs migrations, removes this banner, commits
7. Deploy backend to Railway, frontend to Vercel
8. Update ALLOWED_ORIGINS in Railway to include the Vercel domain

Full procedure with exact commands: SETUP.md. Cross-resource naming convention: NAMING.md. Project context for Claude / coding sessions: CLAUDE.md.

Layout

backend/     # FastAPI + Alembic + Postgres
frontend/    # Next.js App Router
database/    # PostgreSQL schema (auto-applied via docker-compose)
scripts/     # setup.sh, devstart.sh, portal-ai.py, dev-ai-up/down.sh, overnight-debug.sh
docker-compose.yml   # Local Postgres + pgvector
SETUP.md     # First-time per-client deploy procedure
NAMING.md    # Cross-resource naming convention
CLAUDE.md    # Project context for coding sessions

License

Internal use only — Overlook Strategy.