# Keel — the multi-tenant SaaS template

**Django 6 + Next.js 15 + Stripe + Postgres** — a complete, production-ready
SaaS foundation with multi-tenancy, billing, async jobs, document storage, and
the guardrails to keep you from shooting yourself in the foot.

## What Keel is

- **A multi-tenant SaaS foundation** — organizations, memberships, invitations,
  role-based permissions, and per-organisation data isolation out of the box.
- **A billing-ready platform** — Stripe checkout/portal, plan/price sync,
  entitlements (feature flags and limits), seat sync, and an optional
  credit ledger for metered usage.
- **An async job runner** — Celery with tiered task priorities, a resumable
  job runner with idempotent credit settlement, per-organisation concurrency
  control, and live SSE status updates.
- **A document storage layer** — presigned direct uploads to R2/S3,
  checksum verification, soft deletes, and garbage collection.
- **A guardrailed codebase** — seven architecture invariants enforced by CI
  (import contracts, permission-placement lint, audit-presence meta-test,
  coverage floors, OpenAPI drift detection, etc.).

## What Keel is not

- **Not a specific product** — Keel is a template. It has a demo slice
  (`widgets`) to exercise the mechanisms end to end, but you're expected to
  delete it and build your own domain on top of the foundation.
- **Not a low-code platform** — you write Python and TypeScript. There are
  generators (`pnpm gen ...`) to scaffold new resources, jobs, permissions,
  and emails, but they emit readable code in your repo, not a black box.
- **Not a CMS or marketing site** — there is an optional marketing-site
  layer (landing page, pricing, blog via content-collections), but it's
  deliberately decoupled and removable (`docs/marketing-removal.md`).

## Quick start

```bash
# 1. Clone and install
git clone https://github.com/your-org/keel.git
cd keel
pnpm install  # installs JS deps and builds emails/content
cd apps/api && uv sync && cd ../..

# 2. Start infra (Postgres, Redis, Mailpit, MinIO)
pnpm env:up

# 3. Migrate and seed
cd apps/api && uv run python manage.py migrate
uv run python manage.py seed_demo

# 4. Run dev servers (API, web, worker, SSE stream)
pnpm dev:slot

# 5. Open http://app.lvh.me:3000 and log in as [email protected] / demo-password-123
```

## Architecture invariants

1. **Domain logic in services/selectors** — views are thin, tasks delegate.
2. **Authorization in one place** — `organizations/permissions.py` only.
3. **One transaction per service** — external calls on `on_commit()`.
4. **Schema changes are migrations** — reviewed, in VCS.
5. **Async through Tier 1/2** — no bespoke background threads.
6. **Two-layer validation** — serializers at edge, services for invariants.
7. **Every mutating service audited** — `@audited` or `@not_audited(reason)`.

See `docs/architecture.md` for the full walk-through.

## Directory structure

```
keel/
├── apps/
│   ├── api/              # Django 6 + Ninja
│   └── web/              # Next.js 15
├── packages/
│   ├── ui/               # Shared component kit
│   ├── api-client/       # Generated TS client
│   └── emails/           # react-email templates
├── infra/                # Docker Compose (dev/prod)
├── scripts/              # Init, OpenAPI merge, coverage check
└── templates/            # Generator templates (resource/job/permission/email)
```

## Documentation index

- `docs/architecture.md` — the seven invariants, request path, type sync
- `docs/auth-flow.md` — cross-host auth, cookies, CSRF, MFA
- `docs/billing.md` — credits, plans, entitlements, webhooks
- `docs/storage.md` — presigned uploads, lifecycle, providers
- `docs/jobs-and-audit.md` — job runner, idempotency, audit trail
- `docs/deploy-railway.md` — Railway deployment, pgvector
- `docs/maintenance.md` — supported versions, upgrade checklists
- `docs/pre-push.md` — local pre-push gates mirroring CI
- `docs/marketing-removal.md` — how to delete the marketing site
- `docs/query-patterns.md` — selectors, N+1 prevention, pagination
- `docs/boundary-guardrails.md` — unsafe rendering, validation, async boundaries
- `SECURITY.md` — vulnerability reporting, response time
- `CONTRIBUTING.md` — CI gates, invariants, how to contribute
- `CHANGELOG.md` — version history, phases
- `AGENTS.md` — agent-specific guidance (file shape, invariants)
- `CLAUDE.md` — pointer to AGENTS.md

## License

MIT — see LICENSE.

# AGENTS.md

Keel is a Django 6 + Next.js 15 SaaS template. Full detail lives in
docs/architecture.md (the seven invariants, request path, type
synchronisation); this file is the short version an agent needs before
writing a line here.

## Per-app file shape

Every domain app under apps/api/keel/ follows the same seven files.
apps/api/keel/widgets/ is the reference slice — copy its shape, not its content.

```
/
├── models.py         # data shape only
├── services.py       # ORM, transactions, side effects — ALL writes
├── selectors.py      # ALL reads
├── permissions.py    # required permission codes (organizations app only)
├── schemas.py        # shape validation at the edge (Ninja Schema / Pydantic)
├── views.py          # THIN: parse, call service, serialize, return
├── tasks.py          # one-line delegations to services
└── tests/
```

A view, serializer, Celery task, admin page, or management command that
contains a business rule is a bug, not a style choice.

## The seven invariants

| # | Invariant | Enforced by | Verify with |
|---|-----------|-------------|-------------|
| 1 | Domain logic in services/selectors, never views/serializers/tasks/admin | import-linter contract | `cd apps/api && uv run lint-imports` |
| 2 | Authorization in organizations/permissions.py only | check_permission_lint.py | `uv run python ../../scripts/check_permission_lint.py` |
| 3 | One transaction per service function | Code review + tests | Read services.py |
| 4 | Schema changes are migrations | makemigrations --check | `uv run python manage.py makemigrations --check --dry-run` |
| 5 | Async through Tier 1/2 tasks | Code review | Check keel/core/tasks.py usage |
| 6 | Two-layer validation (serializers + services) | Code review | Read views.py + services.py |
| 7 | Every mutating service @audited or @not_audited | Meta-test | `uv run pytest keel/core/tests/test_service_audit_registry.py` |

## Commands reference

| Command | Purpose |
|---------|--------|
| `pnpm bootstrap` | Fresh checkout: install JS + Python deps, build emails |
| `pnpm env:up` / `env:down` | Start/stop Postgres, Redis, Mailpit, MinIO |
| `pnpm env:reset` | Fresh DB: down -v, up, build emails, migrate, seed_demo |
| `pnpm dev:slot` | API, SSE stream, Celery worker and web on this slot's ports |
| `pnpm health` | JSON {api, web, ok}; exit 0 when both answer |
| `pnpm lint` | ruff + ESLint + prettier |
| `pnpm typecheck` | mypy strict + tsc |
| `pnpm test:unit` | Vitest + pytest minus db/redis-marked tests |
| `pnpm test:db` | DB-backed pytest + coverage floors |
| `pnpm e2e [--grep @tag]` | Playwright against this slot |
| `pnpm design:check` | impeccable design detector |

## Slots

FACTORY_SLOT (0-9) is set by the factory chair per worktree.
Every port is its default + slot*100.
The generated .env and apps/web/.env.local carry a managed-by header;
never hand-edit them, and never point a worktree at another slot's services.

## Demo data

seed_demo creates a demo org and one verified user per role
([email protected] etc., password demo-password-123).
It is idempotent and refuses to run without DEBUG.

## Design system

App code composes @keel/ui components and tokens in packages/ui/theme.css.
@shadcn/lint blocks restyling components through className, raw palette
colours, arbitrary values, inline styles and unknown classes.

## Findings

Audit findings (review, Playwright/visual, UX, design detector) are
Markdown files under findings//NNNN-.md with front matter:
type, severity (blocking|major|minor), status (open|fixed|wontfix),
slice, source, evidence. Evidence goes in findings/_evidence/.

@AGENTS.md

Note: CLAUDE.md simply references AGENTS.md - all agent guidance is in the file above.

# Development setup

## Prerequisites

- Python 3.12+ (managed by uv)
- Node.js 22+ (managed by fnm or nvm)
- pnpm 9.5.0+ (corepack-enabled)
- Docker + Docker Compose

## Quick start

```bash
# 1. Clone
git clone https://github.com/your-org/keel.git
cd keel

# 2. Install dependencies
pnpm install  # JS deps + builds emails and content-collections
cd apps/api
uv sync       # Python deps

# 3. Start infrastructure
pnpm env:up   # Postgres, Redis, Mailpit, MinIO

# 4. Migrate and seed
cd apps/api
uv run python manage.py migrate
uv run python manage.py seed_demo

# 5. Run development servers
pnpm dev:slot  # API on 8000, web on 3000, worker, SSE stream

# 6. Open browser
# http://app.lvh.me:3000
# Login: [email protected] / demo-password-123
```

## Why lvh.me and not localhost?

This template uses subdomain-based multi-tenancy:
- `app.lvh.me:3000` - Next.js application
- `api.lvh.me:8000` - Django API
- `lvh.me` resolves to 127.0.0.1 via public DNS

This allows testing cross-subdomain cookies and CORS locally,
which is exactly how production will work with:
- `app.yourdomain.com` - Application
- `api.yourdomain.com` - API

## Environment variables

The factory generates `.env` and `apps/web/.env.local` for you.
Key variables:

```bash
# Django
DJANGO_SECRET_KEY=your-secret-key
DEBUG=True
KEEL_APP_DOMAIN=lvh.me

# Database
DATABASE_URL=postgres://keel:keel@localhost:5432/keel

# Redis
REDIS_URL=redis://localhost:6379/0

# Email (Mailpit in dev)
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=localhost
EMAIL_PORT=1025

# Storage (MinIO in dev)
KEEL_FILES_STORAGE_BACKEND=keel.files.storage.S3CompatibleStorage
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_STORAGE_BUCKET_NAME=keel
AWS_S3_ENDPOINT_URL=http://localhost:9000
```

## Slots system

Multiple worktrees can run simultaneously using slots (0-9):
- Slot 0: API=8000, Web=3000
- Slot 1: API=8100, Web=3100
- Slot N: API=8000+N*100, Web=3000+N*100

Set FACTORY_SLOT environment variable to use a different slot.

## Common commands

```bash
# Run tests
pnpm test:unit    # Fast, no DB
pnpm test:db      # Full test suite with coverage

# Lint and typecheck
pnpm lint
pnpm typecheck

# E2E tests
pnpm e2e          # All Playwright tests
pnpm e2e:baseline # CI gate tests only

# Reset everything
pnpm env:reset    # Wipe DB, migrate, seed
```

# Architecture

## The seven invariants

### 1. Domain logic in services.py/selectors.py

Views, serializers, Celery tasks, admin, and management commands call into
services — they don't contain business rules.

**Enforced by:** import-linter contract in pyproject.toml
**Verify with:** `cd apps/api && uv run lint-imports`

### 2. Authorization in one place

Authorization is expressed only in organizations/permissions.py (Perm codes +
has_perm/registry.register). Services call has_perm, never reimplement a check.

**Enforced by:** scripts/check_permission_lint.py
**Verify with:** `uv run python ../../scripts/check_permission_lint.py`

### 3. One transaction per service function

External calls (Stripe, etc.) go out via transaction.on_commit(), never from
inside an open transaction.

**Enforced by:** Code review + tests
**Verify with:** Read services.py

### 4. Schema changes are migrations

No dashboard or admin-console schema edits. A migration in a feature PR
needs explanation.

**Enforced by:** makemigrations --check in CI
**Verify with:** `uv run python manage.py makemigrations --check --dry-run`

### 5. Async through Tier 1/2 tasks

Tier 1: keel/core/tasks.py shim for simple background work
Tier 2: Celery directly for complex jobs

**Enforced by:** Code review
**Verify with:** Check keel/core/tasks.py usage

### 6. Two-layer validation

Serializers at the HTTP edge, services for invariants.
Client-side Zod is UX only, never enforcement.

**Enforced by:** Code review
**Verify with:** Read views.py + services.py

### 7. Every mutating service audited

@audited(action) or @not_audited(reason=...). A meta-test fails on anything
decorated with neither.

**Enforced by:** Meta-test in test_service_audit_registry.py
**Verify with:** `uv run pytest keel/core/tests/test_service_audit_registry.py`

## Request path

```
Browser → Next.js BFF → Django Ninja → Service → DB
                     ↓
                Stripe/R2/etc (on_commit)
                     ↓
                AuditLog (inline)
```

## Type synchronization

OpenAPI schema merged from Django Ninja + allauth, generated TS client via orval.
CI fails if generated client is stale.

# System diagram

## Deployed architecture

```mermaid
flowchart TB
    subgraph vercel["Vercel"]
        marketing["Next.js 15 — marketing + auth
acme.com"]
        appui["Next.js 15 — application
app.acme.com"]
    end
    
    browser["Browser"]
    stripe["Stripe"]
    resend["Resend (email)"]
    r2["Cloudflare R2 / S3-compatible storage"]
    sentry["Sentry"]
    posthog["PostHog"]
    
    subgraph railway["Railway"]
        api["Django 6 + Ninja (sync)
gunicorn — request/response only"]
        sse["Django ASGI (async)
uvicorn — SSE only, same image"]
        postgres[("Postgres 17")]
        redis[("Redis 7
broker + cache")]
        worker["Celery worker"]
        beat["Celery beat
(scheduler)"]
    end
    
    browser -- "fetch, credentials: include" --> marketing
    browser -- "fetch, credentials: include" --> appui
    browser -- "fetch, credentials: include
api.acme.com" --> api
    browser -- "EventSource
api.acme.com/.../stream" --> sse
    
    stripe -- webhooks --> api
    
    api --> postgres
    sse --> postgres
    api --> redis
    sse --> redis
    redis --> worker
    redis --> beat
    
    api -.-> stripe
    worker -.-> stripe
    worker -.-> resend
    api -.-> r2
    worker -.-> r2
    
    api -.-> sentry
    appui -.-> sentry
    api -.-> posthog
    appui -.-> posthog
```

## Why the SSE service is separate

api.acme.com/…/stream is served by a second Railway service running
the same image, under uvicorn instead of gunicorn. A held-open SSE
connection under the sync worker pool exhausts it at a concurrent-user
count far below what ordinary request/response load testing suggests.

## Two Next.js hosts, one session

acme.com (marketing + auth) and app.acme.com (application) are two
Next.js deployments sharing one sessionid cookie, Domain-scoped to the
registrable parent domain.