Technical Architecture

Atamaia is a three-layer platform on .NET 10, ASP.NET Core, PostgreSQL with pgvector, and EF Core.

Interaction layer     REST API, MCP server, CLI, agents
        |
Core services         Memory, identity, hydration, communication,
                      projects and tasks, standing rules, AI routing,
                      graph, billing, auth
        |
Autonomic layer       Consolidation and other background jobs
        |
PostgreSQL + pgvector

The REST API is the source of truth. MCP, the CLI, and editor integrations are adapters over the same services. Canonical host: https://api.atamaia.ai.

Forgotten shapes are a memory type on the work store. They are not a separate table. See Retired surfaces for surfaces that are no longer on the public API.

Related: AI routing, Agents, Autonomic layer, Memory surfaces, Multi-tenancy.

What each layer is for

The interaction layer is how callers arrive: REST, MCP, the CLI, and agent runs. Core services own identity, memory, hydration, work, rules, and model routing. The autonomic layer runs scheduled maintenance — consolidation, channel polling, and similar jobs — without a caller invoking them. PostgreSQL is the system of record, including vector search.

Tenant-scoped rows

Every tenant-scoped table carries id, guid, tenant_id, audit timestamps, is_active, and is_deleted. Internal joins use id. External references can use guid. Deletes on product surfaces set is_deleted. They do not remove the row.

A few stores are deliberately not tenant-filtered: system settings, interest and support registrations, and log/audit archive tables. Detail: Multi-tenancy.

Main tables

Area Tables Notes
Accounts tenants, users, identities, refresh_tokens, identity_api_keys Identity keys use the prefix atamaia_
Memory memories, memory_tags, hebbian_links, personal_memories, agent_memories Four surfaces. See Memory surfaces
Work projects, project_tasks, task_dependencies, task_notes, docs, facts Task create requires kind and subsystem. See Tasks
Rules standing_rules, standing_rule_memory_links See Standing rules
Graph graph_nodes, graph_edges, graph_drifts See Code graph
Routing ai_providers, ai_models, ai_route_configs, ai_model_groups See AI routing
Agents role definitions, runs, events, escalations See Agents

How it is built

  • Tenant isolation is a query filter, not a check in each controller.
  • Task dependencies refuse a cycle before the row is saved.
  • Tests run against PostgreSQL. jsonb, full text, and pgvector are part of the contract.
  • REST responses use ApiEnvelope<T>. MCP returns the service DTO directly.
  • Chat streams use Open Responses events over server-sent events. The same call shape works for a cloud model and a local llama.cpp server.
  • Memory content and fact values are encrypted at rest. Titles stay readable so search still works.

Authentication

  1. JWT access tokens with refresh rotation. POST /api/auth/login, POST /api/auth/refresh.
  2. Identity API keys, sent as Authorization: Bearer atamaia_….
  3. OAuth social login and the authorization-server surface.

Permission checks are role-based. Identity-owned stores add an owner rule on top. See Memory surfaces.

Production hosts

https://api.atamaia.ai       REST and OpenAPI
https://api.atamaia.ai/mcp   MCP (authentication required)
https://app.atamaia.ai       SPA. Not the API host.

Caddy terminates TLS and routes. Local inference is a provider behind the same routing layer, not a separate application API.

Last updated