System Architecture

IAS is designed around three operational planes that keep a clean separation between cloud coordination, local execution, and repository state. The target-state posture is one strong local execution runtime plus a thin control plane for visibility, approvals, and evidence. Some sections below also describe current framework implementation mechanics where that detail still matters operationally.

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 human-in-the-loop decision requests through structured 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 local execution status, job execution, and activity across repositories
• Briefings -- Health summaries of workspace and agent activity, surfacing opportunities and attention items

Local Execution Plane (Local)

IAS executes work locally on developer machines or CI environments. The preferred product model is a strong governed local runtime that executes against repository state while the Console stays focused on visibility and approvals.

Current framework implementation note:

• the deployable framework still exposes a CLI worker for setup/scaffolding-style jobs
• the deployable framework still exposes a hybrid runner for AI-driven execution jobs
• those components are transitional mechanics, not the preferred long-term product vocabulary

They currently connect to the control plane API over HTTPS, claim jobs from the queue, execute against local repository checkouts, and report results back.

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)         Local execution         Repository (Git)
     |                             |                            |
     |  1. Create goal/job         |                            |
     |                             |                            |
     |  2. Runtime checks jobs     |                            |
     |<----------------------------                             |
     |                             |                            |
     |  3. Runtime 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. Runtime checks jobs -- Local execution checks the control plane for available jobs matching its capabilities and mapped repositories
3. Runtime claims -- Local execution claims a job and receives a time-limited lease, preventing duplicate execution
4. Local execution -- The runtime 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 -- Local execution 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 local execution claims a job, it receives a time-limited lease (typically 10-30 minutes). This lease mechanism prevents duplicate execution. The runtime must send periodic heartbeats to extend the lease. If it crashes or disconnects, the lease expires automatically and the job returns to the queue.

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
• Runtime 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