Orbiteus — A Full-Stack Development Framework for AI Agents. Build custom ERP, CRM & Business Tools in days not months. Start with 80% of the job done.
AI agents touching this repository: read
docs/pre-prompt.mdfirst. It is the canonical stack and convention contract. Skipping it leads to invented dependencies and bypassed framework primitives — both out of bounds.
Orbiteus is a software development framework: your AI agents use it to build your business application — CRM, ERP, HR, WMS, or anything in between. You start with roughly 80% of the work already done. You focus only on the business needs you describe to the agent.
You can ship a genuinely solid app in hours, or at most a few days. When you are ready, you tell the agent to run it on our infrastructure or on servers and environments you specify.
Tell your AI agent to build your app using Orbiteus — that's the whole idea.
The engine already carries the technical baseline: app server, database layer, admin shell, security and tenancy model, audit trail, background jobs, webhooks, portal surface, and AI tools that obey the same rules as people. Your agent works inside this codebase and its contracts (docs/pre-prompt.md) so you are not inventing sessions, queues, or RBAC from scratch.
You start with roughly 80% of the plumbing done. What you focus on is describing your business — who uses the app, what you sell, what you track, what “done” looks like, and the edge cases that matter. What the AI agent and Orbiteus take on together is the heavy technical work: modules, migrations, views, APIs, tests, and shipping something you can run and grow.
Any business — from a one-person shop to a large operator — can use Orbiteus to build whatever internal or customer-facing application you actually need. You are not picking from a short menu of verticals; you describe the process, and your AI agent implements it on top of the engine.
Examples (illustrative, not a limit):
- Replace a rent-by-the-seat sales CRM with one that follows your pipeline stages, approvals, and handoffs — not a vendor’s median company.
- Replace a legacy WMS with a modern stock-and-movements system plus a supplier portal your partners actually log into.
- Replace a third-party “collect reviews” SaaS with your own feedback app tied to your product and domain data — same origin, same rules, your data model.
- Projects, sales, client communication, operations, finance in one coherent surface — you name it. The stack is already there: ~80% of the plumbing is done (auth, multi-tenancy, permissions, audit, APIs, admin UI, background jobs, realtime, and AI agents calling tools under the same rules as people). You add your business logic, integrations, and the last mile of UX that makes it yours — not another hand-rolled session stack or webhook-retry science project.
Files: docs/assets/readme-screenshots/ (1.png–5.png). Swap files there to refresh the gallery.
 |
 |
|---|---|
| 1. Admin dashboard — CRM KPIs, AI assistant, CRM + Technical nav. | 2. Command palette (⌘K) — create records across modules from one search. |
 |
 |
|---|---|
| 3. Webhooks — outbound events, target URL, optional auth headers. | 4. Audit log — tenant-wide trail with filters and field-level diffs. |
 |
|---|
| 5. AI integration — BYOK provider keys, models, per-tenant token budget. |
What ships in the repo, in four layers. Icons are small line-art SVGs in docs/assets/engine-matrix/.
 |
 |
 |
|---|---|---|
| PostgreSQL + pgvector Tenant-scoped data, SQLAlchemy 2 + asyncpg, Alembic migrations, embeddings storage. |
FastAPI core Auto-routed REST, OpenAPI, structured logs, Prometheus metrics, Gunicorn + Uvicorn in production. |
Redis + Celery Cache, rate limits, JTI revocation, outbox, workers, Beat, signed webhooks, realtime Pub/Sub. |
 |
 |
 |
|---|---|---|
| Next.js 16 + Mantine 9 Internal admin shell, auth session, design system ( orbiteus-ui), production next build. |
Views + registry List, form, kanban, calendar, graph from view XML — minimal bespoke TSX per business module. |
Command palette⌘K actions wired to the engine; server-side /api proxy to the FastAPI backend. |
 |
 |
 |
|---|---|---|
| Partner-facing app Separate Next deployable; RBAC scope portal for external users. |
Share links Token exchange and scoped access for customers or vendors (see docs/09-portal-ui.md). |
Same-origin API Next rewrites /api/* to BACKEND_URL — no CORS tricks in the browser for portal traffic. |
 |
 |
 |
|---|---|---|
| BYOK providers Anthropic, OpenAI, Ollama; encrypted tenant credentials; model + budget fields in admin. |
Tool dispatcher Agents call registered tools that use BaseRepository — same RBAC and audit as human writes. |
Chat + embeddings Streaming /api/ai/chat, dashboard prompts, pgvector-backed retrieval (see docs/15-ai-layer.md). |
| Modular monolith | registry.register("your_module") wires models, security, views, actions, and optional AI surface in one place. |
| Zero TSX per business module | Catch-all admin routes + widget registry + view XML — new tables and APIs ship with matching UI patterns. |
| Multi-tenant by default | Repository-enforced tenancy; negative tests for cross-tenant access. |
| Layered RBAC | Model access, record rules, actions, and AI scopes; Redis-backed cache with cross-replica invalidation. |
| Audit | CRUD, auth events, AI tool calls — with redaction hooks for sensitive payloads. |
| Events, outbox, webhooks | Atomic outbox rows, Celery workers, bounded retries, dead-letter path, HMAC-signed delivery. |
| Realtime | SSE + Redis Pub/Sub; tenant-scoped topics; admin lists and portal views can subscribe safely. |
| Infra in one command | Docker Compose: Postgres 16 + pgvector, Redis, backend, admin UI, portal UI (see docs/17-deployment.md). |
| CI gate | Docs checks, pytest + coverage, Vitest, next build, Playwright, audits, secrets baseline, license policy. |
git clone <repo-url>
cd orbiteus
docker compose up --build| Surface | URL |
|---|---|
| Admin UI | http://localhost:3000 |
| Portal UI | http://localhost:3001 (dev compose; prod uses reverse proxy — see deployment docs) |
| API | http://localhost:8000/api |
| OpenAPI | http://localhost:8000/api/docs |
| Metrics | http://localhost:8000/metrics |
Default login (development only): admin@example.com / admin1234.
Rotate BOOTSTRAP_ADMIN_PASSWORD and SECRET_KEY before any production traffic — the production profile refuses default secrets.
+---------------------------+ +---------------------------+
| admin-ui (Next.js 16) | | portal-ui (Next.js 16) |
| internal users (RBAC) | | external users / share |
+-------------+-------------+ +-------------+-------------+
| /api/* (admin-ui: server proxy; portal: rewrites + same-origin)|
v v v v
+------------------------------------------------------------------+
| FastAPI (Gunicorn + UvicornWorker in production) |
| orbiteus_core: registry, repositories, auto-router, AI, |
| auth, RBAC, audit, events, cache, realtime |
| modules: base, auth, crm (reference sample), … |
+----------+----------------------+--------------------+-----------+
| | |
+----------v---------+ +---------v--------+ +--------v---------+
| PostgreSQL 16 | | Redis 7 | | Celery 5 |
| + pgvector | | cache, pub/sub, | | + Beat |
| (+ PgBouncer) | | rate limits, | | outbox drain |
+--------------------+ | session revoke | | + webhooks |
+------------------+------------------+
For the full checklist against the internal Definition of Done, see docs/34-inventory-and-status.md and CHANGELOG.md. In one breath:
- Identity & sessions — JWT access/refresh with rotation, TOTP + recovery codes, password reset flow, HttpOnly cookie session for the admin shell, share tokens for portal.
- Data & rules — Async SQLAlchemy 2, Alembic, soft delete hooks, attribution columns, record rules, strict tenant filters on repositories.
- AI — Provider adapters (Anthropic, OpenAI, Ollama), BYOK storage, streaming chat, tool dispatcher, embeddings table with pgvector.
- Ops — Structured logs, Prometheus metrics families, optional OpenTelemetry, backup scripts and restore-drill documentation.
- Quality gate — GitHub Actions workflow aggregating docs, tests, audits, and license reports.
Binding list lives in docs/pre-prompt.md (stack section). In short: Python 3.13, FastAPI, SQLAlchemy 2 + asyncpg, Pydantic v2, Redis, Celery 5, PostgreSQL 16 + pgvector, Next.js 16 + React 19 + Mantine 9.
Monorepo (npm workspaces): admin-ui and portal-ui only. Cross-cutting widgets and AI surfaces (PromptInput, AIDashboard, shared form widgets) live under admin-ui/src/orbiteus-ui/. When the portal needs the same UX, copy the relevant files into portal-ui (two deployable apps, no separate packages/* workspace).
Full convention: docs/03-modules.md. Skeleton:
modules/<name>/
manifest.py
model/domain.py, mapping.py, schemas.py
controller/repositories.py, services.py, router.py
security/access.yaml
view/*.xml, config.py
actions.py, ai.py, bootstrap.py, docs/spec.md
Register once:
registry.register("your_module")You get migrations against declared tables, REST + OpenAPI for each model, dynamic list/form/kanban/calendar/graph, Command Palette actions, AI tool surface, audit, RBAC, and realtime hooks — without copying CRUD from another module.
# backend
PYTHONPATH=backend pytest -q --cov --cov-report=term
# admin UI unit tests
npm test --workspace admin-ui
# Playwright (stack on :3000)
npm run e2e --workspace admin-uiDetails: docs/20-testing.md and .github/workflows/ci.yml.
| Topic | File |
|---|---|
| Pre-prompt (read first) | docs/pre-prompt.md |
| Architecture | docs/02-architecture.md |
| Modules | docs/03-modules.md |
Data model + ir_* |
docs/04-data-model.md |
| RBAC + multi-tenancy | docs/05-rbac-multitenancy.md |
| Auth | docs/06-auth.md |
| Auto-CRUD API + webhooks | docs/07-api.md |
| Admin UI | docs/08-admin-ui.md |
Design system (Mantine + orbiteus-ui) |
docs/10-design-system.md |
| Portal UI | docs/09-portal-ui.md |
| Realtime | docs/11-realtime.md |
| Events + queues | docs/12-events-and-queues.md |
| Audit | docs/14-audit.md |
| AI layer | docs/15-ai-layer.md |
| Deployment | docs/17-deployment.md |
| Security | docs/18-security.md |
| Testing | docs/20-testing.md |
| Observability | docs/29-observability.md |
| Backups + DR | docs/31-backups-and-dr.md |
| Inventory ledger | docs/34-inventory-and-status.md |
| Definition of Done | docs/35-core-definition-of-done.md |
| ADRs | docs/adr/ |
We welcome fixes, docs, and modules that follow the registry contract. Start with CONTRIBUTING.md (branching, review expectations, and the PR checklist) and AGENTS.md for automation policy.
Current line is v1.0.0. Release notes: CHANGELOG.md. Honest code-vs-docs progress: docs/34-inventory-and-status.md.
MIT — see LICENSE. Third-party manifests: THIRD_PARTY_LICENSES.python.json, THIRD_PARTY_LICENSES.node.json (regenerated via scripts/generate_licenses.sh; CI enforces a no-GPL policy with a small compatibility allow-list — see docs/27-licenses.md).