§ 02 — System overview

The high-level map.

Three runtime tiers — a React SPA, a .NET API, an MCP gateway — plus shared Postgres, Redis, and an optional Langfuse observability stack. Everything else is variations on a theme.

The runtime topology

Tier responsibilities

Frontend: Render chat, project, settings, terminal, admin pages. No business logic. Talks REST for state, WebSocket for streaming. Auth token in localStorage. → §04
API: The brain: orchestrates agent runs, owns the data layer, enforces tenancy, signs JWTs, runs background jobs, talks to MCP service. → §03
MCP service: The hands: a single HTTP host that exposes 11 named MCP endpoints. Some proxy upstream MCP servers (vBox, Jira), others run natively (Azure, price-calculator, Graph integrations). → §05
Postgres: Single shared instance for both API and MCP service. Schema bootstrapped via EnsureCreatedAsync() + inline ALTER TABLE statements at startup. → §06
Redis: Session cache, optional. Falls back to in-memory store when REDIS_URL is absent.
Langfuse: Optional observability stack — captures every LLM call as a Generation under a per-turn trace. Disabled when LANGFUSE_PUBLIC_KEY is empty. → §03·Observability

Repositories on disk

ToDo/                          ← repo root
├── backend/                   ← .NET API solution + tests + Docker for the worker stack
│   ├── src/
│   │   ├── AgenticIT.Infrastructure/   (config, Redis store, token encryptor, Langfuse client)
│   │   ├── AgenticIT.Data/             (DbContext, entities, repositories)
│   │   ├── AgenticIT.Agent/            (orchestrator, agent loop, tools, skills, MCP, headless)
│   │   ├── AgenticIT.Auth/             (JWT, OAuth, vBox, encryption)
│   │   └── AgenticIT.Api/              (Program.cs, endpoints, WS handlers, DI wiring)
│   ├── tests/AgenticIT.Tests/          (Unit/, Integration/, Parity/)
│   ├── docker-compose.yml
│   ├── docker-compose.langfuse.yml
│   └── setup-worker.sh
│
├── frontend/                  ← React 19 + Vite + TypeScript SPA
│   ├── src/pages/             (top-level routes)
│   ├── src/components/        (chat, approval, artifacts, sync, admin)
│   ├── src/hooks/             (data-fetching + integrations)
│   ├── src/lib/               (api.ts, wsClient.ts, router.ts, auth.ts)
│   └── vite.config.ts
│
├── mcp-service/               ← separate .NET MCP gateway service
│   └── backend/src/McpService/
│       ├── Servers/Azure, PriceCalculator, WebSearch, …
│       ├── Proxy/             (vBox, Jira upstream proxies)
│       └── Data/              (IntegrationTokenStore, token refreshers)
│
├── helm/                      ← K8s charts for staging / production
│   └── charts/backend/templates/   (~30 templates)
│
└── .github/workflows/         (ci.yml, cd-staging.yml, cd-production.yml)

Where to read next

02.2

Tech stack

Exact versions, libraries, and the why behind each choice.

→ 02.3

Request lifecycle

Trace one user message from keystroke to streamed token, end to end.

→