Adoption Paths

Oridecon is designed for incremental adoption. You do not install the catalog. You scaffold with the CLI, then add packages as the application grows.

Day one — the CLI

uv add oridecon-cli
oridecon new project my-app --template web-api
cd my-app
oridecon run

That is the supported start. Templates (minimal, api, web-api, graphql, worker, full) pick packages and application.yaml sections — not a second project shape. Feature types live in domains/. App providers live in app-root di/.

Hand-wiring create_app() is possible; the CLI is what generators and oridecon run expect. See Installation and Project Structure.

Starter — a web API

Enough to serve HTTP with OpenAPI. No database, no cache, no auth — fine for prototypes and early services.

• oridecon + oridecon-contracts — DI container, Application, YAML config, Result
• oridecon-web — ASGI, controllers, middleware, OpenAPI (the web-api template)

oridecon new project my-app --template web-api
oridecon run

Tip

This is a complete API server. Add persistence when you have something to persist — not because the framework requires it.

Standard — persistence, auth, cache

Most production APIs live here.

• oridecon-sql — async Postgres / MySQL / SQLite, repositories, migrations
• oridecon-cache — response cache, session store, rate-limiter backing
• oridecon-auth — JWT, RBAC, route guards, password hashing
• oridecon-testing — fakes, test beds, compliance suites (uv add --dev)

oridecon add database
oridecon add auth
uv add oridecon-cache
uv add --dev oridecon-testing

Note

You already have the CLI from day one. oridecon add writes the YAML section and the dependency so you do not hand-edit both.

Advanced — jobs, events, search, tenancy

Reach for these when a feature needs them — not as a bundle.

• oridecon-search — Meilisearch, Elasticsearch, Typesense, or SQL FTS
• oridecon-storage — uploads, CDN, presigned URLs
• oridecon-tasks — background jobs, cron, workers
• oridecon-events — domain events, CQRS
• oridecon-notification — email, SMS, push
• oridecon-webhook — outbound webhooks with retry and signing
• oridecon-monitor + oridecon-resilience — health, metrics, circuit breakers, retries
• oridecon-tenancy — multi-tenant resolution and isolation

Jobs and events talk to resilience through contracts, not a hard dependency. See Compatibility.

AI-powered

Add AI on top of a working app. The 17 AI packages never import each other; the orchestrator discovers them via entry points.

• oridecon-ai-llm — OpenAI, Anthropic, Google, local models
• oridecon-ai-rag + oridecon-vector — chunk, embed, retrieve, cite
• oridecon-ai-agents + oridecon-ai-skills — tools, strategies, sub-agents
• oridecon-ai-memory + oridecon-ai-session — episodic / semantic memory, conversation lifecycle
• oridecon-ai-mcp — MCP server and client
• oridecon-ai-guard, oridecon-ai-governance, oridecon-ai-evaluation, oridecon-ai-prompt — safety, policy, eval, templates
• oridecon-ai-workers + oridecon-ai-observability + oridecon-ai-feedback — batch work, cost, feedback

Tip

You can install oridecon-ai-llm without RAG, or oridecon-vector without any AI package. Layers: AI Architecture.

Decision flow

Starting a new project?
├── Prototype or microservice → CLI + web-api template
├── Standard web app or API   → add sql, auth, cache, testing
├── Jobs / events / search    → add those packages one at a time
└── AI features               → ship the HTTP app first, then oridecon-ai-llm

Each step is a superset of the one before it. Moving forward is uv add / oridecon add, not a rewrite.

---

See Choosing Backends for infrastructure, and Compatibility for extras and driver strings.