# Architecture

AI Workspace is organized around explicit boundaries: profile configuration, raw evidence, canonical memory, derived retrieval, local services, and AI client adapters.

## System Flow

```text
Communication / screenshots / archives / manual notes
        ↓
Raw inbox evidence
        ↓
Agent or human curation
        ↓
Canonical Markdown project knowledge
        ↓
Derived local index
        ↓
Read-only MCP context server
        ↓
AI clients and agent workflows
```

## Responsibility Boundaries

| Layer | Responsibility | Canonical? |
|---|---|---|
| `core/` | Reusable architecture and operating model | yes, for workspace design |
| `profiles/<profile>/` | Project-specific configuration and assumptions | yes, for profile config |
| `workspaces/<profile>/project-knowledge/` | Human-readable project memory for the active profile | yes, for project facts |
| `workspaces/<profile>/inbox/` | Raw evidence captured from connectors | no |
| `.aiw/indexes/` | Rebuildable search indexes | no |
| `.aiw/runtime/` | PID files, logs, local service state | no |
| `scripts/aiw/` | Profile-aware service/index utilities | code source |
| `scripts/mcp/` | MCP servers exposing local context | code source |
| `apps/` | Local UI surfaces such as the macOS menu bar app | code source |

## Current Repository Shape

Profile-owned data lives under `workspaces/<profile>/`. Reusable code must resolve paths from `profiles/<profile>/workspace.json` rather than hardcoding profile-specific locations.

Current data layout:

```text
profiles/<profile>/workspace.json   # where profile data lives
workspaces/<profile>/project-knowledge/
workspaces/<profile>/inbox/
.aiw/indexes/<profile>/
```

## Design Principles

- Keep the smallest useful context loaded by default.
- Prefer just-in-time retrieval over dumping the entire workspace into prompts.
- Keep human-readable Markdown as the project source of truth.
- Keep raw evidence outside canonical memory until explicitly promoted.
- Keep profile-specific facts out of `core/` and generic scripts.
- Make local services observable through a single service manager.
- Treat cloud memory systems as optional, not authoritative.

## Why This Shape

Current AI workflow guidance emphasizes context engineering: the model should receive the smallest high-signal context needed for the task. This workspace supports that by combining:

- structured Markdown memory for durable facts;
- raw evidence stores for auditability;
- local indexes for retrieval;
- MCP tools/resources for AI clients;
- profile-specific boundaries for reuse across projects.