Architecture Overview¶

Astra is built around a hard product constraint: hot-path reads must stay fast (see PRD §25). Cached layers back that goal; synchronous database reads on latency-sensitive user paths are avoided by design.

Layers¶

Applications use the Astra SDK, which talks to a microkernel-style core (actors, task graph, scheduler, messaging, state). Below that: Postgres, Redis, Memcached, and object storage.

flowchart TB
  subgraph apps [Applications]
    SDK[Astra SDK]
  end
  subgraph kern [Kernel]
    AR[Actor runtime]
    TG[Task graph]
    SCH[Scheduler]
    BUS[Messaging]
    ST[State / events]
  end
  subgraph infra [Infrastructure]
    PG[(Postgres)]
    RD[(Redis)]
    MC[(Memcached)]
    OBJ[Object storage]
  end
  SDK --> AR
  AR --> BUS
  TG --> PG
  SCH --> RD
  BUS --> RD
  ST --> PG
  SDK --> TG

Security and data plane¶

Clients use TLS to the API gateway with JWT auth. Service-to-service traffic uses mTLS. Tool execution is sandboxed; secrets are injected via Vault (or equivalent), not baked into images. See Security and PRD §18.

Kubernetes namespaces (summary)¶

Goal → task → result (flow)¶

1. Client submits a goal for an agent (with optional inline documents).
2. Goal path validates, assembles agent context (system_prompt + rules + skills + context_docs), then planning produces a task DAG with context embedded.
3. Task service persists the graph; scheduler finds ready tasks and dispatches to shard queues.
4. Workers claim work, run tool/sandbox steps, then complete or fail tasks. Failed tasks retry or move to dead letter.
5. Dependent tasks unlock; the cycle continues until the graph finishes.

Chat flow (Phase 10)¶

Users can also interact via WebSocket chat on the api-gateway. Chat sessions connect to chat-capable agents with streaming responses, optional tool invocation, and memory context. The Slack adapter bridges Slack Events API to the chat/goal pipeline for workspace-based interactions.

Dashboard¶

The super-admin dashboard at /superadmin/dashboard/ provides platform-wide visibility: service health, agents, goals, workers, approvals, cost, and Slack configuration. Pastel glass-style design with light/dark theme toggle.

sequenceDiagram
  participant C as Client
  participant GW as API gateway
  participant GS as Goal path
  participant PL as Planner
  participant TS as Task service
  participant SCH as Scheduler
  participant Q as Work queues
  participant W as Workers
  C->>GW: Goal
  GW->>GS: Forward
  GS->>PL: Plan
  PL->>TS: Persist graph
  SCH->>TS: Ready tasks
  SCH->>Q: Dispatch
  W->>Q: Claim
  W->>TS: Complete / fail

Caching (10ms read path)¶

Hot reads use Redis and Memcached with TTLs described in PRD §13. Writes go durable first, then events, then cache refresh — so caches can lag slightly behind the database by design.

Hardware targets¶

Single codebase; graceful CPU fallback when accelerators unavailable. Detection via runtime.GOOS or build tags. See PRD §20 and Deployment.