django-angee

The first and default runtime implementation of angee.ai — Django on the backend, React on the frontend.

Angee is the agent-native generative execution environment: define your services, models, permissions, and AI agents in one place, run one command, get a fully operational platform with a typed GraphQL surface, REBAC permissions, an MCP tool layer, and AI agents that can deploy, debug, and develop alongside you. The umbrella project + Go CLI lives at angee-go. This repo is the runtime implementation that turns your [tool.angee] declarations into a running Django + React application.

Status: bootstrapped, working example in examples/angee-demo/. The framework contract is locked; the strangle plan that lifts the remaining domain packages out of the production fyltr-django app is tracked in R-09.

Try it now

The shortest path to a running stack — copy/paste:

# install the angee CLI
curl https://angee.ai/install.sh | sh

# clone + scaffold + start the dev loop
git clone https://github.com/<org>/django-angee
cd django-angee/examples/angee-demo
angee init --dev --yes        # creates .angee/data/, runs migrate, seeds users
angee dev                     # build watcher + runserver:8100 + Vite:5173

Open http://127.0.0.1:5173/ and log in as admin / admin.

Full walkthrough + repo layout + REBAC smoke flow: examples/angee-demo/README.md.

What this provides

You write abstract Python packages that declare models, GraphQL contributions, permission rules, and agent configurations. The composition engine (angee build) merges every installed package into one deterministic runtime tree (runtime/) with concrete Django apps, a unified GraphQL schema, a REBAC permission graph, and a generated React typed-hook bundle. Then you ship.

Surface	What you get	Source of truth
Models	Concrete Django models composed from multiple packages' abstract bases. Built-in sqid, audit timestamps, REBAC-scoped querysets.	docs/PACKAGE.md
GraphQL	Composed Strawberry schema with auto-emitted CRUD + filters + ordering + pagination, plus hand-written contributions. Persisted-operations contract. Subscriptions over Channels.	docs/GRAPHQL.md
Permissions	SpiceDB-compatible REBAC layer. Every package contributes a permissions.zed fragment; the build merges them. LocalBackend default; ANGEE_PERMISSIONS_BACKEND=spicedb flips the backend without touching app code.	docs/PERMISSIONS.md
MCP	Hand-curated AngeeMcpTool registry that exposes operations as MCP tools for AI agents. Persisted-op manifest + fastmcp dispatch.	docs/MCP.md
Frontend	React block library (@angee/sdk + per-package React bindings) with codegen from the printed SDL. View IR drives list / detail / form rendering — declared once in Python, rendered uniformly in React.	docs/FRONTEND.md
CLI	manage.py angee {build, migrate, doctor, fixtures}. The Go binary angee adds parent-walk discovery + angee dev orchestrator (build watcher + runserver + Vite + extras with line-mode + pane-mode TUI).	docs/BUILD.md, R-16
Migrations	Per-package, version-keyed, three-phase emission. angee migrate runs the build to refresh wrappers, then Django's migrate. Destructive-op prompt scheduled for v0.2.	R-12

Read first

All design docs live under docs/. Start with:

• docs/ARCHITECTURE.md — system blueprint, build pipeline, runtime tree, project-mode .angee/ layout.
• docs/PACKAGE.md — package contract, [tool.angee], owns/extends, lifecycle hooks.
• docs/BUILD.md — angee build pipeline, CLI surface, determinism contract.
• docs/PERMISSIONS.md — REBAC blueprint (three tiers, polymorphic subjects).
• docs/GRAPHQL.md, docs/MCP.md, docs/FRONTEND.md — surface contracts.
• docs/DECISIONS.md — locked R-XX decisions and the RISK register.

Repo layout

django-angee/
├── pyproject.toml              # uv workspace root + dev-group toolchain
├── package.json                # pnpm workspace root (React frontends)
├── pnpm-workspace.yaml
├── melos.yaml                  # Melos workspace (Flutter frontends, future)
├── packages/                   # five first-party Python packages
│   ├── django-angee/           # framework (composition + DSL + base mixins + CLI)
│   │   ├── angee/              # PEP 420 namespace; no __init__.py at this level
│   │   └── tests/              # framework tests + shared fixtures
│   ├── django-angee-auth/      # User, Group, REBAC, LocalBackend, auth providers
│   ├── django-angee-drive/     # files (skeleton)
│   ├── django-angee-unibox/    # messaging (skeleton)
│   └── django-angee-agents/    # AI orchestration (skeleton)
├── examples/
│   └── angee-demo/             # reference consumer (start here — see its README)
└── docs/                       # design docs (source of truth)

There is no src/ directory at the repo root. This repo is a library; only consumers (the example, fyltr-django) have a Django deployment. Tests build synthetic consumer projects in tmp dirs via the synthetic_project pytest fixture in packages/django-angee/tests/conftest.py.

Toolchain

# Python — install all workspace members + dev toolchain (pytest, ruff, mypy)
uv sync --group dev

# React — install all frontend workspace members
pnpm install

# Flutter — bootstrap all Flutter packages (when frontend-flutter/ subdirs exist)
melos bootstrap

# Tests
uv run pytest

# Lint
uv run ruff check .

angee build / angee migrate / angee dev run inside CONSUMER projects (the example, or your own), not here. See examples/angee-demo/README.md and docs/ARCHITECTURE.md § 12 for the consumer-side workflow.

Sibling repos

• angee-go — the umbrella project. The Go binary angee is a polyglot CLI: native compose-mode commands (init, up, chat) plus project-mode forwarders that exec into this repo's manage.py angee.
• fyltr-django — the production consumer being progressively ported per the R-09 strangle plan. First port: accounts/ → django-angee-auth.

Future runtimes (Rust, Node) plug into the same Go CLI via the adapter interface in angee-go/docs/RUNTIMES.md.

License

TBD — see LICENSE.