# ai-swiss/base architecture

> Architecture diagram of the GitHub repository ai-swiss/base, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai-swiss/base
- Repository: https://github.com/ai-swiss/base

## Overview

BASE is a framework and reference implementation for expressing a human-approved working method in portable, editable files, then using that method to guide AI tools. The central workflow is to structure and review the method, inventory its resources, route a request to relevant guidance, and provide the assistant with an appropriately bounded context. The graph also preserves documented integrations, the Studio, diagnostics, and evaluation. Some subsystems are represented by directory paths because their source was not sampled; their internal links are omitted where evidence is unavailable.

Main entry points: [`tools/base-core.mjs`](https://github.com/ai-swiss/base/blob/main/tools/base-core.mjs) (BASE core broker), [`tools/eval/orchestrate.mjs`](https://github.com/ai-swiss/base/blob/main/tools/eval/orchestrate.mjs) (Evaluation orchestration), [`tools/core/route-service.mjs`](https://github.com/ai-swiss/base/blob/main/tools/core/route-service.mjs) (Route computation), [`tools/cli/init.mjs`](https://github.com/ai-swiss/base/blob/main/tools/cli/init.mjs) (Initialize project)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_method["Method and resources"]
  node_method_files["Method files"]
  node_init["Initialize project<br/>[init.mjs]"]
  node_frontmatter["Resource metadata<br/>[frontmatter.mjs]"]
end

subgraph group_runtime["Core execution"]
  node_inventory["Resource inventory<br/>[base-core.mjs]"]
  node_policy["Access and egress<br/>[egress.mjs]"]
  node_context["Context packing<br/>[context-pack.mjs]"]
  node_rankers["Resource ranking<br/>[rankers.mjs]"]
  node_routing["Route decision<br/>[routing.mjs]"]
  node_route_service["Route computation<br/>[route-service.mjs]"]
  node_broker["BASE core broker<br/>[base-core.mjs]"]
  node_local_index["Local index<br/>[route.mjs]"]
  node_semantic_ranker["Semantic ranker<br/>[ranker.mjs]"]
end

subgraph group_interfaces["User and tool interfaces"]
  node_mcp["MCP server<br/>[index.ts]"]
  node_mcp_adapter["Core adapter"]
  node_studio_ui["Studio interface<br/>[App.tsx]"]
  node_studio_server["Studio server<br/>[server.mjs]"]
  node_docs["Documentation site<br/>[content.ts]"]
end

subgraph group_quality["Diagnostics and evaluation"]
  node_doctor["Corpus diagnosis<br/>[diagnose.mjs]"]
  node_eval["Evaluation orchestration<br/>[orchestrate.mjs]"]
  node_eval_harness["Process harness<br/>[broker-harness.mjs]"]
  node_eval_packages["Evaluation and models"]
  node_llm["LLM adapters"]
end

node_person(("Method author"))
node_ai_tool(("AI tool"))

node_person -->|"defines and approves"| node_method_files
node_person -->|"requests setup"| node_init
node_init -->|"initializes"| node_broker
node_method_files -->|"provides method"| node_ai_tool
node_broker -->|"parses metadata"| node_frontmatter
node_broker -->|"checks egress"| node_policy
node_broker -->|"packs context"| node_context
node_route_service -->|"scores candidates"| node_rankers
node_route_service -->|"decides route"| node_routing
node_broker -.->|"orchestrates routing"| node_route_service
node_mcp -->|"delegates to"| node_mcp_adapter
node_mcp_adapter -->|"brokers requests"| node_broker
node_ai_tool -->|"uses integration"| node_mcp
node_studio_ui -.->|"uses API"| node_studio_server
node_studio_server -.->|"serves BASE operations"| node_broker
node_doctor -->|"loads inventory"| node_broker
node_eval -->|"runs experiment"| node_eval_packages
node_eval -->|"builds harness"| node_eval_harness
node_eval -->|"creates model clients"| node_llm
node_local_index -.->|"supports local routing"| node_semantic_ranker
node_person -.->|"browses guidance"| node_docs

click node_init "https://github.com/ai-swiss/base/blob/main/tools/cli/init.mjs"
click node_frontmatter "https://github.com/ai-swiss/base/blob/main/tools/core/frontmatter.mjs"
click node_inventory "https://github.com/ai-swiss/base/blob/main/tools/base-core.mjs"
click node_policy "https://github.com/ai-swiss/base/blob/main/tools/core/egress.mjs"
click node_context "https://github.com/ai-swiss/base/blob/main/tools/core/context-pack.mjs"
click node_rankers "https://github.com/ai-swiss/base/blob/main/tools/core/rankers.mjs"
click node_routing "https://github.com/ai-swiss/base/blob/main/tools/core/routing.mjs"
click node_route_service "https://github.com/ai-swiss/base/blob/main/tools/core/route-service.mjs"
click node_broker "https://github.com/ai-swiss/base/blob/main/tools/base-core.mjs"
click node_mcp "https://github.com/ai-swiss/base/blob/main/mcp/src/index.ts"
click node_mcp_adapter "https://github.com/ai-swiss/base/blob/main/mcp/src/base-core-adapter.ts"
click node_studio_ui "https://github.com/ai-swiss/base/blob/main/tools/studio/ui/src/App.tsx"
click node_studio_server "https://github.com/ai-swiss/base/blob/main/tools/studio/server.mjs"
click node_doctor "https://github.com/ai-swiss/base/blob/main/tools/doctor/diagnose.mjs"
click node_eval "https://github.com/ai-swiss/base/blob/main/tools/eval/orchestrate.mjs"
click node_eval_harness "https://github.com/ai-swiss/base/blob/main/tools/eval/broker-harness.mjs"
click node_eval_packages "https://github.com/ai-swiss/base/tree/main/packages/base-eval"
click node_llm "https://github.com/ai-swiss/base/tree/main/packages/base-llm"
click node_local_index "https://github.com/ai-swiss/base/blob/main/packages/base-index-local/src/route.mjs"
click node_semantic_ranker "https://github.com/ai-swiss/base/blob/main/packages/base-ranker-semantic/src/ranker.mjs"
click node_docs "https://github.com/ai-swiss/base/blob/main/packages/base-docs-site/src/lib/content.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_method_files,node_init,node_frontmatter toneBlue
class node_inventory,node_policy,node_context,node_rankers,node_routing,node_route_service,node_broker,node_local_index,node_semantic_ranker toneAmber
class node_mcp,node_mcp_adapter,node_studio_ui,node_studio_server,node_docs toneMint
class node_doctor,node_eval,node_eval_harness,node_eval_packages,node_llm toneRose
class node_person,node_ai_tool toneIndigo
```

## Components

### Method and resources

- **Method files**
- [Initialize project](https://github.com/ai-swiss/base/blob/main/tools/cli/init.mjs): `tools/cli/init.mjs`
- [Resource metadata](https://github.com/ai-swiss/base/blob/main/tools/core/frontmatter.mjs): `tools/core/frontmatter.mjs`

### Core execution

- [Resource inventory](https://github.com/ai-swiss/base/blob/main/tools/base-core.mjs): `tools/base-core.mjs`
- [Access and egress](https://github.com/ai-swiss/base/blob/main/tools/core/egress.mjs): `tools/core/egress.mjs`
- [Context packing](https://github.com/ai-swiss/base/blob/main/tools/core/context-pack.mjs): `tools/core/context-pack.mjs`
- [Resource ranking](https://github.com/ai-swiss/base/blob/main/tools/core/rankers.mjs): `tools/core/rankers.mjs`
- [Route decision](https://github.com/ai-swiss/base/blob/main/tools/core/routing.mjs): `tools/core/routing.mjs`
- [Route computation](https://github.com/ai-swiss/base/blob/main/tools/core/route-service.mjs): `tools/core/route-service.mjs`
- [BASE core broker](https://github.com/ai-swiss/base/blob/main/tools/base-core.mjs): `tools/base-core.mjs`
- [Local index](https://github.com/ai-swiss/base/blob/main/packages/base-index-local/src/route.mjs): `packages/base-index-local/src/route.mjs`
- [Semantic ranker](https://github.com/ai-swiss/base/blob/main/packages/base-ranker-semantic/src/ranker.mjs): `packages/base-ranker-semantic/src/ranker.mjs`

### User and tool interfaces

- [MCP server](https://github.com/ai-swiss/base/blob/main/mcp/src/index.ts): `mcp/src/index.ts`
- [Core adapter](https://github.com/ai-swiss/base/blob/main/mcp/src/base-core-adapter.ts): `mcp/src/base-core-adapter.ts`
- [Studio interface](https://github.com/ai-swiss/base/blob/main/tools/studio/ui/src/App.tsx): `tools/studio/ui/src/App.tsx`
- [Studio server](https://github.com/ai-swiss/base/blob/main/tools/studio/server.mjs): `tools/studio/server.mjs`
- [Documentation site](https://github.com/ai-swiss/base/blob/main/packages/base-docs-site/src/lib/content.ts): `packages/base-docs-site/src/lib/content.ts`

### Diagnostics and evaluation

- [Corpus diagnosis](https://github.com/ai-swiss/base/blob/main/tools/doctor/diagnose.mjs): `tools/doctor/diagnose.mjs`
- [Evaluation orchestration](https://github.com/ai-swiss/base/blob/main/tools/eval/orchestrate.mjs): `tools/eval/orchestrate.mjs`
- [Process harness](https://github.com/ai-swiss/base/blob/main/tools/eval/broker-harness.mjs): `tools/eval/broker-harness.mjs`
- [Evaluation and models](https://github.com/ai-swiss/base/tree/main/packages/base-eval): `packages/base-eval`
- [LLM adapters](https://github.com/ai-swiss/base/tree/main/packages/base-llm): `packages/base-llm`

### Other components

- **Method author**
- **AI tool**

## Connections

- Method author → Method files: defines and approves (evidence: `README.md`)
- Method author → Initialize project: requests setup (evidence: `README.md`)
- Initialize project → BASE core broker: initializes (evidence: `tools/cli/init.mjs`)
- Method files → AI tool: provides method (evidence: `README.md`)
- BASE core broker → Resource metadata: parses metadata (evidence: `tools/base-core.mjs`)
- BASE core broker → Access and egress: checks egress (evidence: `tools/base-core.mjs`)
- BASE core broker → Context packing: packs context (evidence: `tools/base-core.mjs`)
- Route computation → Resource ranking: scores candidates (evidence: `tools/core/route-service.mjs`)
- Route computation → Route decision: decides route (evidence: `tools/core/route-service.mjs`)
- BASE core broker → Route computation: orchestrates routing (evidence: `tools/base-core.mjs`)
- MCP server → Core adapter: delegates to (evidence: `mcp/src/index.ts`)
- Core adapter → BASE core broker: brokers requests
- AI tool → MCP server: uses integration (evidence: `README.md`)
- Studio interface → Studio server: uses API
- Studio server → BASE core broker: serves BASE operations
- Corpus diagnosis → BASE core broker: loads inventory (evidence: `tools/doctor/diagnose.mjs`)
- Evaluation orchestration → Evaluation and models: runs experiment (evidence: `tools/eval/orchestrate.mjs`)
- Evaluation orchestration → Process harness: builds harness (evidence: `tools/eval/orchestrate.mjs`)
- Evaluation orchestration → LLM adapters: creates model clients (evidence: `tools/eval/orchestrate.mjs`)
- Local index → Semantic ranker: supports local routing
- Method author → Documentation site: browses guidance
