AI Architecture

The Oridecon AI platform is 17 packages. Six layers describe the usual stack. Each layer builds on the one below it, and every AI package follows the same dependency rule: import only from oridecon and oridecon-contracts, never from each other.

graph TD
    A["Integration Layer<br/>oridecon-ai-mcp"] --> B["Infrastructure Layer<br/>oridecon-ai-workers, -observability, -feedback"]
    B --> C["Memory Layer<br/>oridecon-ai-memory, -session"]
    C --> D["Reasoning Layer<br/>oridecon-ai-agents, -skills"]
    D --> E["Knowledge Layer<br/>oridecon-ai-rag, oridecon-vector"]
    E --> F["Base Layer<br/>oridecon-ai-llm"]

oridecon-ai is the orchestrator. It discovers the packages below through entry points and wires them in the container. Application code talks to protocols, not to the orchestrator’s internals.

1. Base layer — oridecon-ai-llm

The LLM client protocol.

• Provider routing: OpenAI, Anthropic, Google, and local models behind one interface
• Thinking suppression: control over chain-of-thought output from reasoning models
• Token tracking: usage accounting and cost estimation

All higher layers depend on this package for model access — through contracts, not imports.

2. Knowledge layer — oridecon-ai-rag + oridecon-vector

Retrieval-augmented generation and vector storage.

• Document ingestion: chunking, embedding, and indexing pipelines
• Retrieval: hybrid search (semantic + keyword), re-ranking, contextual compression
• Vector storage: pgvector, Qdrant, Pinecone, and in-memory

Note

oridecon-vector is also used outside the AI subsystem — for example, by recommendation engines. It lives as a general-purpose package, not an AI-only one.

3. Reasoning layer — oridecon-ai-agents + oridecon-ai-skills

Multi-step reasoning and tool use.

• Agents: loop-based reasoning with tool selection, error recovery, and structured output
• Skills: reusable tool definitions that agents can discover and invoke at runtime
• Orchestration: parallel tool execution, conditional branching, sub-agent delegation

4. Memory layer — oridecon-ai-memory + oridecon-ai-session

Conversation history and persistent knowledge.

• Episodic memory: per-conversation message history with summarization
• Semantic memory: cross-session facts, user preferences, learned knowledge
• Session management: conversation lifecycle, state persistence, expiry

5. Integration layer — oridecon-ai-mcp

Expose AI capabilities as Model Context Protocol tools, resources, and prompts.

• MCP server: wrap agents, RAG pipelines, and skills as MCP tools
• MCP client: connect to external MCP servers from within agents
• Discovery: dynamic tool registration and capability advertisement

6. Infrastructure layer — oridecon-ai-workers + oridecon-ai-observability + oridecon-ai-feedback

Production AI infrastructure.

• Background processing: async work for embedding, indexing, and batch inference
• Observability: token usage, latency, cost attribution per-user / per-conversation
• Feedback loops: user feedback collection, preference data pipelines

Also in the catalog

These follow the same “never import each other” rule and sit beside the layers above:

Package	Role
oridecon-ai-guard	Input/output safety and content filtering
oridecon-ai-governance	Policy, audit trails, budget tracking
oridecon-ai-evaluation	Benchmarks and quality gates
oridecon-ai-prompt	Templates, composition, optimization
oridecon-ai-relay	Route and fan-out model calls across providers
oridecon-ai-relay-gateway	Ingress, auth, and quota at the relay edge

Note

Architectural rule: AI packages must never import from each other. oridecon-ai-agents does not import oridecon-ai-rag — it receives RAG results through its interfaces. This keeps the dependency graph flat and avoids circular coupling.

Dependency direction

Each layer depends only on the layers below it. The base layer depends only on oridecon and oridecon-contracts. The integration layer can optionally consume any layer below it, but never introduces upward dependencies.

Next Steps

• Adoption Paths — when to add AI (after a working HTTP app)
• Choosing Backends — vector stores
• AI agents guide — tools and strategies
• RAG guide — chunk, retrieve, cite
• Platform overview — per-package docs