orbiteus

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.md first. It is the canonical stack and convention contract. Skipping it leads to invented dependencies and bypassed framework primitives — both out of bounds.

What is Orbiteus?

Orbiteus is an AI agent engine for domain business applications — operational CRM, club management, HR, integrations, and custom tools that fill gaps generic SaaS cannot. Your agents implement your processes on top of guardrails (auth, RBAC, audit, APIs, admin shell, jobs, realtime, AI tools).

The bundled CRM module is a framework demo, not the product you must ship. See docs/40-reference-product-caltrain.md for a reference domain app (fitness CRM replacing a rent-by-the-seat sales tool).

You can ship a solid domain app in days when you follow docs/39-spec-driven-agent-workflow.md: Ask → Spec → Implement → Verify.

HOW TO USE IT?

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.

What you can build with Orbiteus

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.

Screenshots

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.

Engine matrix

What ships in the repo, in four layers. Icons are small line-art SVGs in docs/assets/engine-matrix/.

Backend

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.

Frontend (admin-ui)

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.

Portal UI

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.

Built-in AI layer

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).

Capabilities (proof, not philosophy)

Quick start

git clone <repo-url>
cd orbiteus
docker compose up --build

Default login (development only): [email protected] / admin1234.

Optional demo dataset (curated companies, users, attachments):

# One-time cleanup after old bulk seed + load demo (add to .env or export):
SEED_DEMO_DATA=1 RESET_DEMO_DATA=1 docker compose up --build

# Or manually:
docker compose exec backend python -m scripts.seed_demo --reset

Demo users (password demo1234): [email protected], [email protected], [email protected].
Rotate BOOTSTRAP_ADMIN_PASSWORD and SECRET_KEY before any production traffic — the production profile refuses default secrets.

Architecture at a glance

+---------------------------+     +---------------------------+
|   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       |
                        +------------------+------------------+

What ships in the box (summary)

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.

For engineers (stack & modules)

Tech stack (authoritative detail)

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).

Module layout

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.

Running tests

# 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-ui

Details: docs/20-testing.md and .github/workflows/ci.yml.

Documentation map

Contributing

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.

Versioning + release

Current line is v1.1.0. Release notes: CHANGELOG.md. Honest code-vs-docs progress: docs/34-inventory-and-status.md.

License

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).