# albertoracerro/jarvisos_v1 architecture

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

- Interactive diagram: https://gitdiagram.com/albertoracerro/jarvisos_v1
- Repository: https://github.com/albertoracerro/jarvisos_v1

## Overview

JarvisOS is a local-first engineering R&D workspace that brings project records, AI assistance, simulation, CAD/CAE, and evidence into one operator workflow. An engineer works from the frontend, manages project knowledge and engineering inputs, runs studies or engineering tools, and inspects results and provenance. AI requests pass through JarvisOS execution and egress policy before reaching a local model or an approved external provider. The README documents several additional product branches; their internal wiring is not established by the sampled excerpts, so those links are kept broad or omitted.

Main entry points: [`backend/app/main.py`](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/main.py) (Application API), [`backend/app/modules/ai/gateway.py`](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/ai/gateway.py) (AI execution), [`frontend/src/App.tsx`](https://github.com/albertoracerro/jarvisos_v1/blob/master/frontend/src/App.tsx) (Operator UI), [`backend/app/modules/ai/routes.py`](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/ai/routes.py) (AI request routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator workstation"]
  node_frontend["Operator UI<br/>[App.tsx]"]
  node_router["UI routing<br/>[useAppRouter.ts]"]
  node_api["API client<br/>[client.ts]"]
end

subgraph group_project["Project knowledge"]
  node_modeling["Engineering records<br/>[routes.py]"]
  node_knowledge["Project knowledge<br/>[routes.py]"]
  node_literature["Literature"]
  node_search["Project search<br/>[routes.py]"]
end

subgraph group_engineering["Engineering workflow"]
  node_runner["Run execution<br/>[routes.py]"]
  node_kernel["Process models<br/>[flowsheet.py]"]
  node_studies["Engineering studies<br/>[studies.py]"]
  node_bluecad["BLUECAD<br/>[routes.py]"]
  node_evidence["Run evidence<br/>[evidence.py]"]
end

subgraph group_ai["AI and agents"]
  node_ai_routes["AI request routes<br/>[routes.py]"]
  node_gateway["AI execution<br/>[gateway.py]"]
  node_policy["Egress policy<br/>[egress_service.py]"]
  node_providers["Provider registry"]
  node_hermes["Hermes agent<br/>[routes.py]"]
end

subgraph group_runtime["Runtime integrations"]
  node_backend["Application API<br/>[main.py]"]
  node_database[("SQLite state<br/>[database.py]")]
  node_local_model["Local model runtime<br/>[routes.py]"]
end

node_engineer(("Engineer"))
node_external_provider["External AI provider"]

node_engineer -->|"operates"| node_frontend
node_frontend -->|"resolves routes"| node_router
node_frontend -->|"requests data"| node_api
node_api -->|"calls API"| node_backend
node_backend -->|"dispatches records"| node_modeling
node_backend -->|"dispatches knowledge"| node_knowledge
node_backend -->|"dispatches literature"| node_literature
node_backend -->|"dispatches search"| node_search
node_modeling -->|"reads and writes"| node_database
node_knowledge -->|"reads and writes"| node_database
node_literature -->|"reads and writes"| node_database
node_backend -->|"dispatches runs"| node_runner
node_runner -->|"executes models"| node_kernel
node_backend -->|"dispatches studies"| node_studies
node_backend -->|"dispatches CAD"| node_bluecad
node_bluecad -->|"produces evidence"| node_evidence
node_backend -->|"dispatches AI"| node_ai_routes
node_ai_routes -->|"executes request"| node_gateway
node_gateway -->|"checks egress"| node_policy
node_gateway -->|"selects provider"| node_providers
node_gateway -->|"runs locally"| node_local_model
node_gateway -.->|"approved external call"| node_external_provider
node_ai_routes -.->|"routes agent turns"| node_hermes

click node_frontend "https://github.com/albertoracerro/jarvisos_v1/blob/master/frontend/src/App.tsx"
click node_router "https://github.com/albertoracerro/jarvisos_v1/blob/master/frontend/src/app/useAppRouter.ts"
click node_api "https://github.com/albertoracerro/jarvisos_v1/blob/master/frontend/src/api/client.ts"
click node_backend "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/main.py"
click node_modeling "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/modeling/routes.py"
click node_knowledge "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/project_knowledge/routes.py"
click node_literature "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/memory/literature_routes.py"
click node_search "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/project_search/routes.py"
click node_database "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/core/database.py"
click node_runner "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/runner/routes.py"
click node_kernel "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/process_kernel/flowsheet.py"
click node_studies "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/engineering/studies.py"
click node_bluecad "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/bluecad/routes.py"
click node_evidence "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/bluecad/evidence.py"
click node_ai_routes "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/ai/routes.py"
click node_gateway "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/ai/gateway.py"
click node_policy "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/ai/egress_service.py"
click node_providers "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/ai/provider_registry.py"
click node_hermes "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/agents/hermes/routes.py"
click node_local_model "https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/local_ai/runtime/routes.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_frontend,node_router,node_api toneBlue
class node_modeling,node_knowledge,node_literature,node_search toneAmber
class node_runner,node_kernel,node_studies,node_bluecad,node_evidence toneMint
class node_ai_routes,node_gateway,node_policy,node_providers,node_hermes toneRose
class node_backend,node_database,node_local_model,node_engineer,node_external_provider toneIndigo
```

## Components

### Operator workstation

- [Operator UI](https://github.com/albertoracerro/jarvisos_v1/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [UI routing](https://github.com/albertoracerro/jarvisos_v1/blob/master/frontend/src/app/useAppRouter.ts): `frontend/src/app/useAppRouter.ts`
- [API client](https://github.com/albertoracerro/jarvisos_v1/blob/master/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Project knowledge

- [Engineering records](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/modeling/routes.py): `backend/app/modules/modeling/routes.py`
- [Project knowledge](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/project_knowledge/routes.py): `backend/app/modules/project_knowledge/routes.py`
- [Literature](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/memory/literature_routes.py): `backend/app/modules/memory/literature_routes.py`
- [Project search](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/project_search/routes.py): `backend/app/modules/project_search/routes.py`

### Engineering workflow

- [Run execution](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/runner/routes.py): `backend/app/modules/runner/routes.py`
- [Process models](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/process_kernel/flowsheet.py): `backend/app/modules/process_kernel/flowsheet.py`
- [Engineering studies](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/engineering/studies.py): `backend/app/modules/engineering/studies.py`
- [BLUECAD](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/bluecad/routes.py): `backend/app/modules/bluecad/routes.py`
- [Run evidence](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/bluecad/evidence.py): `backend/app/modules/bluecad/evidence.py`

### AI and agents

- [AI request routes](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/ai/routes.py): `backend/app/modules/ai/routes.py`
- [AI execution](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/ai/gateway.py): `backend/app/modules/ai/gateway.py`
- [Egress policy](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/ai/egress_service.py): `backend/app/modules/ai/egress_service.py`
- [Provider registry](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/ai/provider_registry.py): `backend/app/modules/ai/provider_registry.py`
- [Hermes agent](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/agents/hermes/routes.py): `backend/app/modules/agents/hermes/routes.py`

### Runtime integrations

- [Application API](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/main.py): `backend/app/main.py`
- [SQLite state](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/core/database.py): `backend/app/core/database.py`
- [Local model runtime](https://github.com/albertoracerro/jarvisos_v1/blob/master/backend/app/modules/local_ai/runtime/routes.py): `backend/app/modules/local_ai/runtime/routes.py`

### Other components

- **Engineer**
- **External AI provider**

## Connections

- Engineer → Operator UI: operates
- Operator UI → UI routing: resolves routes
- Operator UI → API client: requests data
- API client → Application API: calls API
- Application API → Engineering records: dispatches records
- Application API → Project knowledge: dispatches knowledge
- Application API → Literature: dispatches literature
- Application API → Project search: dispatches search
- Engineering records → SQLite state: reads and writes
- Project knowledge → SQLite state: reads and writes
- Literature → SQLite state: reads and writes
- Application API → Run execution: dispatches runs
- Run execution → Process models: executes models
- Application API → Engineering studies: dispatches studies
- Application API → BLUECAD: dispatches CAD
- BLUECAD → Run evidence: produces evidence
- Application API → AI request routes: dispatches AI
- AI request routes → AI execution: executes request
- AI execution → Egress policy: checks egress
- AI execution → Provider registry: selects provider
- AI execution → Local model runtime: runs locally
- AI execution → External AI provider: approved external call
- AI request routes → Hermes agent: routes agent turns