Architecture

ContextUnity is a uv workspace monorepo of modular Python services communicating over gRPC. Each service has a single responsibility and shares types through ContextCore (packages/core).

Ecosystem Map

architecture-ecosystem

Communication Pattern

All inter-service communication uses the ContextUnit protocol. Every RPC call carries a typed envelope with:

Payload — domain-specific data (google.protobuf.Struct / validated JsonDict)
Provenance — ordered trace of processing stages
Security — scopes for access control
Tracing — trace_id and parent_unit_id for distributed observability

architecture-sequence

Repository layout

contextunity/
├── packages/
│   ├── core/          # Kernel — types, protos, tokens, SDK clients
│   └── cli/           # ContextCLI — local stack orchestration
├── services/
│   ├── router/        # Agent orchestration (LangGraph)
│   ├── brain/         # Vectors, memory, taxonomy, RAG storage
│   ├── worker/        # Temporal + Huey workflows
│   ├── shield/        # Enterprise security
│   └── forge/         # Starlette dashboard + FastMCP + Lab tools
├── extensions/
│   ├── commerce/      # Django PIM + harvester (commercial)
│   ├── rag/           # Chat / Telegram gateway
│   └── spatial/       # Geospatial scaffold (planned capabilities)
├── types/django/      # Shared strict pyright baseline + Django stubs
├── website/           # This documentation site (Astro Starlight)
└── pyrightconfig.json # Single strict gate for all production src/

Service roles

Component	Role	Protocol	License
-----------	------	----------	---------
ContextCore	Shared kernel — types, protos, tokens, config	library	Apache 2.0
ContextCLI	Local dev orchestration, migrations, stack targets	CLI	Apache 2.0
ContextRouter	Agent orchestration — LangGraph, tools, PII privacy	gRPC	Apache 2.0
ContextBrain	Knowledge — vectors, memory, taxonomy, RAG storage	gRPC	Apache 2.0
ContextWorker	Durable workflows — Temporal (primary), Huey (local)	gRPC	Apache 2.0
ContextShield	Token signing, AI firewall, secrets vault	gRPC	Commercial
ContextForge	Observability dashboard, Brain Admin UI, DevTools/Docs MCP	HTTP + MCP	Apache 2.0
ContextCommerce	E-commerce PIM, harvester, matching	Django + federated tools	Apache 2.0
ContextRAG	HTTP/Telegram chat gateway (Router-backed)	HTTP + gRPC client	Commercial
ContextSpatial	Voice/geo/AR scaffold	—	Commercial

Technology stack

Language: Python 3.13+
Inter-service: gRPC with Protocol Buffers (packages/core/protos/)
Agent framework: LangGraph (LangChain)
Database: PostgreSQL 16+ with pgvector and ltree
Task engines: Temporal.io (Worker), Huey/Redis (Commerce, local Worker)
LLM providers: OpenAI, Anthropic, Vertex AI, Groq, Perplexity, and others via Router
Package management: uv workspace
Static typing: basedpyright strict — see Code Quality & Types
Configuration: Pydantic via get_core_config() (env + YAML merge)