System Architecture

IAS is designed around three operational planes that keep a clean separation between cloud coordination, local execution, and repository state. This architecture ensures that source code never leaves your machines while still providing real-time visibility and team coordination through the Console.

Tech Stack

Three Planes

Console Plane (Cloud)

The IAS Console is the web-based command center. It provides visibility into agent activity, approval workflows for decision requests, and coordination across repositories and team members. The Console runs as a Next.js application backed by Convex. It never executes code -- it only coordinates.

The Console handles:

• Workspace and workstream management -- Create and configure workspaces, organize work with workstreams, manage team members and roles
• Goal creation and refinement -- Submit intakes, review proposals, approve goals, and track progress through the execution lifecycle
• Decision request inbox -- Review and answer agent questions through structured human-in-the-loop workflows
• Repository onboarding -- Register repositories, trigger bootstrap and build context jobs, manage repository metadata
• Context Lake management -- View and manage project context items, knowledge artifacts, and integration-sourced content
• Agent monitoring -- Real-time visibility into worker status, job execution, and activity across all repositories
• Briefings -- Health summaries of workspace and agent activity, surfacing opportunities and attention items

Worker Plane (Local)

Workers are Node.js processes that run on developer machines or CI environments. They connect to the Console's control plane API over HTTPS, claim jobs from the queue, execute them against local repository checkouts, and report results back.

IAS provides two worker components:

• CLI Worker (ias worker start): Handles coordination and setup jobs -- install_ias (bootstrap), create_run, context_architect, apply_decision, update_git_policy, and git_repair. These are short-lived, deterministic operations that scaffold repositories, apply decisions, and manage configuration.
• Hybrid Runner (ias runner start): Handles AI-driven execution jobs -- work and pr_review -- using the Codex SDK for automated agent turns. These are longer-running operations where an AI agent writes code, reviews pull requests, or performs implementation tasks.

You can start both components together with ias agent start, or run them independently depending on your needs.

Repository Plane (Local)

Repositories are the source of truth. All project context, agent decisions, run artifacts, and code changes live in Git. The IAS framework scaffold (docs/ias/) provides the structured surface that agents read from and write to.

Key repository artifacts include:

• docs/ias/project-context.md -- World model snapshot with tech stack, constraints, and production status
• docs/ias/context/base-goal.md -- Overarching outcome statement
• docs/ias/context/inputs.md -- Links to external references (tickets, PRDs, architecture docs)
• docs/ias/runs/ -- Goal-scoped directories with intent, proposals, task state, and evidence
• docs/ias/decisions/ -- Records of choices made by humans and agents
• docs/ias/gaps.md -- Tracked knowledge gaps and open questions

Because these artifacts are committed to Git, they are versioned, portable, and accessible to any tool -- not just IAS.

Data Flow

The following sequence illustrates how a typical job flows through the system:

Console (Convex)              Worker (Local)              Repository (Git)
     |                             |                            |
     |  1. Create goal/job         |                            |
     |                             |                            |
     |  2. Worker polls for jobs   |                            |
     |<----------------------------                             |
     |                             |                            |
     |  3. Worker claims job       |                            |
     |<----------------------------                             |
     |                             |                            |
     |                             |  4. Execute locally        |
     |                             |---------------------------->
     |                             |                            |
     |                             |  5. Read context, write    |
     |                             |       changes              |
     |                             |<----------------------------
     |                             |                            |
     |  6. Report result           |                            |
     |<----------------------------                             |
     |                             |                            |
     |  7. Update UI (real-time)   |                            |
     |                             |                            |

1. Job created -- A goal or job is created in the Console (by a human through the UI or by the system via orchestration)
2. Worker polls -- The local worker polls the control plane for available jobs matching its capabilities and mapped repositories
3. Worker claims -- The worker claims a job and receives a time-limited lease, preventing other workers from duplicating the work
4. Local execution -- The worker executes the job against the local repository checkout
5. Read and write -- The agent reads project context from docs/ias/ and writes code, decisions, and artifacts to the repository
6. Report result -- The worker reports the outcome (commit SHA, changed files, status) back to the control plane
7. Real-time update -- The Console UI updates instantly via Convex subscriptions -- no polling or manual refresh required

Leases and Concurrency

When a worker claims a job, it receives a time-limited lease (typically 10-30 minutes). This lease mechanism prevents two workers from executing the same job simultaneously. Workers must send periodic heartbeats to extend their lease. If a worker crashes or disconnects, the lease expires automatically and the job returns to the queue for another worker to claim.

No Source Code in the Cloud

A core design principle of IAS is that source code never leaves the local machine. The Convex backend stores only coordination metadata:

• Job definitions and status (pending, running, done, failed, blocked)
• Commit SHAs, branch references, and PR URLs
• Decision request text and resolutions
• Worker heartbeats and capabilities
• Repository identity (remote URL hash, not the URL itself)
• Run pointers and milestone tracking

Source code, diffs, and file contents stay in the local Git checkout. The Console shows status, decisions, and activity -- not code. This design makes IAS suitable for use with client codebases where source code cannot be uploaded to third-party services.

Data Policy Modes

Each workspace can be configured with a data policy that controls what content is stored in the cloud. This is enforced at both write time (content is filtered before storage) and read time (queries respect the policy).

Default Allowlist

In metadata_only mode, an allowlist mechanism lets you selectively permit specific fields that are needed for Console usability:

• repo.label -- Repository display name
• intake.title -- Goal title
• intake.rawContent -- Goal description text

These defaults ensure the Console remains usable (you can identify repositories and goals) without exposing source code or detailed project content. The allowlist can be customized per workspace.

Real-Time Updates

Convex provides real-time subscriptions out of the box. When agent status changes, jobs complete, or decision requests arrive, the Console UI updates instantly without polling. This is especially valuable for:

• Monitoring long-running agent operations -- See progress as it happens without refreshing the page
• Team coordination -- Multiple team members see the same live state simultaneously
• Decision request responsiveness -- Get notified immediately when an agent needs your input, and have agents resume automatically when you respond

The real-time nature of the system means the Console is always showing the current state of your workspace, not a cached snapshot.

Further Reading

• Authentication -- How humans and machines authenticate
• Control Plane API -- HTTP endpoints for worker communication
• Execution Modes -- Interactive, automated, and Console-managed modes
• Context Lake -- The unified knowledge layer