Skip to content

Layered Architecture

Design rule

HeyAira coordinates work but does not own every artifact involved in that work. Each layer has one clear source of truth.

GitHub / Git
files, code, branches, commits, pull requests
        |
        | repository references: URL, branch, commit SHA
        v
HeyAira durable state
memory, decisions, tasks, work-session receipts
        ^
        | authenticated MCP calls
        |
AI harnesses and threads
Codex first; other harnesses later

Layer 1: repository and artifacts

GitHub/Git owns:

  • source files and documentation;
  • commit history;
  • branches and tags;
  • pull requests and code review;
  • reproducible code checkpoints.

HeyAira stores references to these objects but never copies repository contents into PostgreSQL. GitHub credentials remain outside the HeyAira MCP credential and are managed by each execution environment or a separately authorized GitHub App.

For the first prototype, GitHub API integration is unnecessary. Workers use normal Git commands. HeyAira only records where work started and where it ended.

Uncommitted local changes are not a reliable handoff. A completed code work session should normally produce a commit on a dedicated branch before another session continues it.

Layer 2: durable HeyAira state

PostgreSQL owns:

  • projects;
  • project memberships and role assignments;
  • project-to-repository bindings;
  • token and OAuth subject-to-project mappings;
  • memory entries and decisions;
  • tasks and optimistic versions;
  • work-session receipts;
  • bounded continuity snapshots and idempotency records;
  • links to repository branches and commits.

This layer is model-independent and harness-independent. It contains durable facts needed to understand and continue work, but not conversation transcripts or repository files.

Project tenancy

Project is the tenant and security boundary. Every memory entry, task, work-session receipt and repository binding belongs to a project. A user may belong to multiple projects through explicit memberships with roles such as owner, admin, contributor and viewer.

Repository bindings are many-to-many. A project may use multiple repositories, and a repository may be referenced by multiple projects. HeyAira stores repository identity, GitHub App installation references and Git checkpoints; it never copies repository contents into PostgreSQL.

Layer 3: MCP interface and access boundary

The MCP server exposes a small tool surface over Streamable HTTP.

Its responsibilities are:

  • authenticate every request;
  • derive the project from the credential, never from model input;
  • enforce project boundaries for every lookup and relation;
  • validate task-version updates atomically;
  • provide clear, model-readable tool descriptions and results;
  • avoid logging secrets and memory bodies.

The startup contract is continuity_context: one bounded, read-only projection of the authenticated project containing recent memory, open tasks, and recent work-session receipts. Append operations use stable idempotency keys where a client may retry after losing a response. Task updates continue to use optimistic versions, and (task_id, session_ref) prevents duplicate work receipts. See Continuity Protocol.

The public authorization boundary follows the MCP authorization specification: OAuth 2.1 Authorization Code with PKCE, protected-resource metadata, authorization-server metadata, resource indicators, exact redirect validation, project scopes and audience-bound short-lived access tokens. The existing project-scoped static Bearer path may remain available for internal Codex and CLI compatibility, but it is not the public registration protocol.

OAuth authorization is provider-neutral. GitHub OAuth or a GitHub App may be used later for GitHub identity or repository operations, but a GitHub token is never accepted as or passed through as a HeyAira MCP token.

The deployable pilot exposes one protocol endpoint at https://mcp.heyaira.eu/mcp. MCP clients discover tools through the protocol; the human-facing setup and tool catalogue live at /docs. PostgreSQL is never mapped to a public host port. TLS and the public edge are separate deployment concerns from the Python application.

Layer 4: execution sessions

A harness owns live execution:

  • the active thread;
  • the model and its context window;
  • local tools and filesystem access;
  • Git credentials;
  • starting, pausing, and resuming work.

HeyAira records a work receipt for a session but does not treat a thread as durable memory. A session may disappear, be archived, or become unavailable. Its durable result must therefore be understandable without resuming that exact thread.

Layer 5: public edge and registration

The public edge terminates HTTPS for mcp.heyaira.eu and forwards only the MCP traffic to the rootless heyaira service. It may be implemented with an approved reverse proxy or Cloudflare tunnel. The edge must preserve the Authorization header for the MCP service while excluding it from logs.

This layer is required for a registerable remote pilot, but it does not route tasks between models. DNS, TLS, and edge configuration must remain isolated from Voyana and must be verified independently.

Layer 6: routing and orchestration — deferred

A future orchestration layer may provide:

  • routing models;
  • task queues and scheduling;
  • model or harness selection;
  • asynchronous question mailboxes;
  • adapters that resume or message a specific thread;
  • retries, timeouts, and supervision.

This layer is intentionally absent from the first prototype. It must be built on top of validated durable state rather than mixed into the initial storage service.

Ownership matrix

Information Source of truth
Source code and files Git repository
Branches and commit history Git repository
Decisions and rationale HeyAira memory
Task status and handoff HeyAira tasks
Which session performed work HeyAira work-session receipt
Live conversation context Harness thread
GitHub credentials Harness/environment
Project membership and roles HeyAira PostgreSQL
Repository access grant GitHub App installation and project binding
HeyAira project credentials Protected client/server configuration
Future thread wake-up Harness-specific adapter

Continuing a code task

  1. A new thread authenticates to HeyAira.
  2. It reads active tasks, decisions, and the latest work receipts.
  3. It obtains the repository URL, branch, and commit SHA.
  4. It fetches and checks out that state using Git.
  5. It performs a bounded change and runs tests.
  6. It commits the result.
  7. It updates the HeyAira task using the expected version.
  8. It appends a work receipt with the resulting commit, tests, next step, and blockers.

Asking a previous session a question

Durable state should normally make this unnecessary. If clarification is still needed, a later HeyAira version can store a question addressed to a work-session reference.

Storing a question is portable. Automatically waking the target thread is not: it requires a harness-specific adapter and a supported API or local integration. Therefore live thread messaging is not part of the first MVP.

The eventual flow may be:

requesting model -> HeyAira question -> harness adapter -> target thread
target response  -> HeyAira answer   -> requesting model

Until such adapters exist, the work receipt and Git state must be sufficient for another session to continue independently.