angee-django

Developer framework and base addons for building Django + React applications on the Angee platform.

For developers, not end users. This repository is the framework source for teams building Angee applications and addons. If you want a product to use, start with a product-specific distribution built on Angee.

Public alpha / active refactor. Angee is being opened while major addon, API, and UI surfaces are still moving. Use it for exploration and feedback, not production. Roadmap and compatibility guarantees are still in progress.

What is this?

angee-django is the framework, the base addons that ship with it, and the first and default Host for Angee — a platform for building agent-native applications that humans and agents operate together.

Angee comes in two halves:

• The operator — a Go control plane (repo ang-ee/angee-operator) that pulls source repositories and composes them into Workspaces (Sources and/or agentic configuration) and Stacks (dev or prod), running them on docker-compose or process-compose.
• This repository — the thin composition framework that assembles a working Django + GraphQL + React application from addons.

In one line: the operator runs things; angee-django decides what those things are.

New here? Start with Get Started.

Architecture at a glance

   ┌──────────────────────────────────────────────────────────────┐
   │  angee operator   (Go control plane — CLI · REST · GraphQL)  │
   │  pulls git Sources → composes Workspaces (a set of Sources   │
   │  and/or agentic config) and Stacks (dev or prod), runs them  │
   └─────────────────────────────┬────────────────────────────────┘
                                 │ runs as a Service
   ┌──────────────────────────────────────────────────────────────┐
   │  angee-django   ·   THIS REPO   ·   the default Host         │
   │                                                              │
   │    addons  (source models · GraphQL · REBAC · React views)   │
   │        │                                                     │
   │        │  manage.py angee build                              │
   │        ▼                                                     │
   │    runtime/   →   Django + GraphQL + React application       │
   └──────────────────────────────────────────────────────────────┘

Requirements

• Python ≥ 3.14 and uv
• Node ≥ 22.13 and pnpm
• The angee CLI — brew install ang-ee/tap/angee, or use the release installer below
• Docker (container Services), process-compose (local Services), and git (git Sources)

Quick start

Before angee init, check for an existing current or ancestor angee.yaml. If one exists, it already owns this checkout: use that ANGEE_ROOT — never initialize a stack under a source checkout.

Angee runs as a stack: angee init renders a project host whose manifest declares the consolidated framework and optional external repositories as sources, and angee dev materializes them and boots. You normally work on this source inside a framework-dev stack's src workspace.

brew install ang-ee/tap/angee      # or: curl -fsSL https://raw.githubusercontent.com/ang-ee/angee-operator/main/scripts/install.sh | sh
angee init myproject               # dev is the default template; add -y for non-interactive use
cd myproject
angee dev                          # materialize sources and boot everything

On macOS, create the stack in a normal working directory, not under /tmp: that symlinked path currently fails the operator's persistence check. angee dev is the only supported way to bring the whole local stack up; angee up starts container services only. Never start Django, Vite, Daphne, or workers by hand. For the full onboarding path (one-shot management commands and isolated workspaces), see Get Started → Set it up.

Repository layout

This repository holds the framework's source surfaces together:

• angee/ — the model and data contracts, ASGI and Celery seams, and the manage.py angee build composer.
• addons/ — the standard folder addons, including the GraphQL runtime, with co-located web fragments.
• packages/ — the published @angee/* React packages and workshops.
• examples/ — showcase consumer addons and the reference e2e suite.
• templates/ — Copier sources for projects, stacks, workspaces, and services.
• docs/, tests/ — intent documentation and the merged contract suite.

The optional personal-messaging bridges remain in ang-ee/angee-messaging-bridges.

The full annotated layout lives in AGENTS.md.

Documentation

This repo follows a simple rule: the code is the spec; the docs carry the intent.

• Get Started — what Angee is, what you can build, and your first run. Start here.
• Features — the complete capability list and how each part works.
• Glossary — shared vocabulary (addon, composer, host, source model, seams…).
• Opinionated stack — which library owns which concern, and what is locked versus proposed.
• Development guidelines · Backend · Frontend — process and language rules.
• Composer — how addon contracts become a runnable project.
• AGENTS.md — the constitution, repository layout, and how the framework composes.
• docs.angee.ai — the full site: the operator's concepts, the angee.yaml manifest, templates, commands, and the REST + GraphQL API.

Generated API references — extracted from the code's own docstrings and TSDoc on every docs build — are published on the site: the backend / Python reference and the frontend / React reference.

Community & support

• Docs & concepts — docs.angee.ai.
• Bugs & feature requests — open an issue.
• Security reports — please report privately; see the Security Policy (security@angee.ai). Do not open a public issue for vulnerabilities.

Contributing

Contributions are welcome — this is a public alpha and feedback is especially valuable. Start with CONTRIBUTING.md, which points at the constitution in AGENTS.md and the process in development guidelines.

• Bring the stack up with angee --root "$angee_root" dev against the resolved stack root containing angee.yaml; the framework source slot is not that root. Never start individual processes by hand; restart them through the angee operator, the stack's management service, which keeps running while it restarts the application (Restart the running stack).
• Follow Checks for backend, frontend, schema, and browser verification before opening a pull request. It distinguishes prescribed local checks from the coverage currently provided by CI.
• By participating you agree to uphold our Code of Conduct.

Notable changes are recorded in CHANGELOG.md.

Roadmap & status

Early alpha preview. Production-readiness is targeted for Q3 2026 — a target, not a promise — and arrives capability-by-capability. See Get Started for the current built-versus-ahead breakdown.

License

Copyright © 2026 Angee, Inc. Licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later). The LGPL is drafted as additional permissions on top of the GPL, so both texts ship: LICENSE (the Lesser additional permissions) and LICENSE.GPL (the GNU General Public License v3.0 they extend).

Addons and applications built on Angee are yours to license as you choose, including proprietary — the LGPL's terms apply to Angee itself.