# key1lee/ai-os architecture

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

- Interactive diagram: https://gitdiagram.com/key1lee/ai-os
- Repository: https://github.com/key1lee/ai-os

## Overview

AI-OS is a shared engineering layer for otherwise independent projects; its documented Py.Dev runtime provides a provider-neutral model router, while projects retain their own rules, permissions, deterministic checks, and state. The local caller submits JSON through the CLI, and the router applies shared configuration and policy before provider handling. The tree and excerpts do not show the CLI entry point or provider dispatch calls, so those links are omitted; provider adapters are shown as separate runtime components.

Main entry points: [`py_dev/router.py`](https://github.com/key1lee/ai-os/blob/main/py_dev/router.py) (Model Router), [`README.md`](https://github.com/key1lee/ai-os/blob/main/README.md) (Engineering Standards), [`py_dev/providers/openai.py`](https://github.com/key1lee/ai-os/blob/main/py_dev/providers/openai.py) (OpenAI Provider), [`py_dev/providers/parsed.py`](https://github.com/key1lee/ai-os/blob/main/py_dev/providers/parsed.py) (Parsed Provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared AI Layer"]
  node_ai_os["Engineering Standards<br/>[README.md]"]
  node_skills["Reusable Skills"]
end

subgraph group_runtime["Py.Dev Runtime"]
  node_router["Model Router<br/>[router.py]"]
  node_context["Context Policy<br/>[context_policy.py]"]
  node_intelligence["Intelligence<br/>[intelligence.py]"]
  node_openai["OpenAI Provider<br/>[openai.py]"]
  node_parsed["Parsed Provider<br/>[parsed.py]"]
end

node_projects["Independent Projects"]
node_caller(("JSON Caller"))

node_caller -->|"submits JSON"| node_router
node_router -.->|"provider dispatch"| node_openai
node_router -.->|"provider dispatch"| node_parsed
node_projects -->|"uses shared guidance"| node_ai_os

click node_ai_os "https://github.com/key1lee/ai-os/blob/main/README.md"
click node_skills "https://github.com/key1lee/ai-os/tree/main/skills"
click node_router "https://github.com/key1lee/ai-os/blob/main/py_dev/router.py"
click node_context "https://github.com/key1lee/ai-os/blob/main/py_dev/context_policy.py"
click node_intelligence "https://github.com/key1lee/ai-os/blob/main/py_dev/intelligence.py"
click node_openai "https://github.com/key1lee/ai-os/blob/main/py_dev/providers/openai.py"
click node_parsed "https://github.com/key1lee/ai-os/blob/main/py_dev/providers/parsed.py"

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_ai_os,node_skills toneBlue
class node_router,node_context,node_intelligence,node_openai,node_parsed toneAmber
class node_projects,node_caller toneIndigo
```

## Components

### Shared AI Layer

- [Engineering Standards](https://github.com/key1lee/ai-os/blob/main/README.md): `README.md`
- [Reusable Skills](https://github.com/key1lee/ai-os/tree/main/skills): `skills`

### Py.Dev Runtime

- [Model Router](https://github.com/key1lee/ai-os/blob/main/py_dev/router.py): `py_dev/router.py`
- [Context Policy](https://github.com/key1lee/ai-os/blob/main/py_dev/context_policy.py): `py_dev/context_policy.py`
- [Intelligence](https://github.com/key1lee/ai-os/blob/main/py_dev/intelligence.py): `py_dev/intelligence.py`
- [OpenAI Provider](https://github.com/key1lee/ai-os/blob/main/py_dev/providers/openai.py): `py_dev/providers/openai.py`
- [Parsed Provider](https://github.com/key1lee/ai-os/blob/main/py_dev/providers/parsed.py): `py_dev/providers/parsed.py`

### Other components

- **Independent Projects**
- **JSON Caller**

## Connections

- JSON Caller → Model Router: submits JSON (evidence: `README.md`)
- Model Router → OpenAI Provider: provider dispatch
- Model Router → Parsed Provider: provider dispatch
- Independent Projects → Engineering Standards: uses shared guidance (evidence: `README.md`)