# sun7485/union-steel architecture

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

- Interactive diagram: https://gitdiagram.com/sun7485/union-steel
- Repository: https://github.com/sun7485/union-steel

## Overview

UNION OS is a factory operating system for project-based steel fabrication. Office users prepare and plan work, manage production and materials, and review quality and performance; floor supervisors and QC record execution in an offline-first app. Those interactions go through the API, which is the documented single write path, to tenant-isolated Postgres/PGlite storage. The graph also preserves imports, background processing, and UNION AI/MCP capabilities. API-to-domain wiring is summarized at the documented subsystem level; sampled excerpts do not establish individual route-to-engine calls.

Main entry points: [`services/api/src/index.ts`](https://github.com/sun7485/union-steel/blob/master/services/api/src/index.ts) (API service), [`apps/office/src/App.tsx`](https://github.com/sun7485/union-steel/blob/master/apps/office/src/App.tsx) (Office workspace), [`apps/floor/src/App.tsx`](https://github.com/sun7485/union-steel/blob/master/apps/floor/src/App.tsx) (Floor app), [`apps/floor/src/lib/queue.ts`](https://github.com/sun7485/union-steel/blob/master/apps/floor/src/lib/queue.ts) (Offline event queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["User applications"]
  node_office["Office workspace<br/>[App.tsx]"]
  node_office_api["Office API client<br/>[api.ts]"]
  node_floor["Floor app<br/>[App.tsx]"]
  node_floor_queue["Offline event queue<br/>[queue.ts]"]
  node_floor_storage[("Local queue storage<br/>[idb.ts]")]
  node_floor_api["Floor API client<br/>[api.ts]"]
end

subgraph group_api["API and processing"]
  node_api_service["API service<br/>[index.ts]"]
  node_api_routes["Domain endpoints"]
  node_worker["Background jobs<br/>[index.ts]"]
end

subgraph group_domain["Factory domain"]
  node_core["Domain logic"]
  node_imports["Import processing<br/>[importing.ts]"]
  node_planning["Planning and readiness<br/>[schedule.ts]"]
  node_production["Production tracking<br/>[floor.ts]"]
  node_materials_quality["Materials and quality<br/>[material.ts]"]
  node_insights["Insights and performance<br/>[forecast.ts]"]
end

subgraph group_data["Persistence"]
  node_db_client["Database client<br/>[client.ts]"]
  node_db_schema[("Tenant data<br/>[index.ts]")]
end

subgraph group_ai["AI access"]
  node_office_ai["Office AI interface<br/>[UnionAi.tsx]"]
  node_ai_service["AI tools and routing<br/>[service.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
end

node_office_users(("Office staff"))
node_floor_users(("Floor staff"))
node_mcp_client(("MCP client"))

node_office_users -->|"use"| node_office
node_floor_users -->|"use"| node_floor
node_office -->|"requests"| node_office_api
node_office_api -->|"calls API"| node_api_service
node_floor -->|"requests"| node_floor_api
node_floor -->|"queues events"| node_floor_queue
node_floor_queue -->|"persists"| node_floor_storage
node_floor_queue -->|"syncs events"| node_floor_api
node_floor_api -->|"calls API"| node_api_service
node_api_service -->|"dispatches"| node_api_routes
node_api_routes -->|"uses domain logic"| node_core
node_api_service -->|"queries"| node_db_client
node_db_client -->|"uses schema"| node_db_schema
node_worker -->|"background processing"| node_api_service
node_imports -->|"domain operations"| node_core
node_office -->|"opens"| node_office_ai
node_office_ai -->|"requests AI"| node_office_api
node_api_routes -->|"serves AI tools"| node_ai_service
node_ai_service -->|"uses engines"| node_core
node_mcp_client -->|"asks tools"| node_mcp
node_mcp -->|"executes tools"| node_ai_service
node_mcp -->|"calls endpoints"| node_api_service

click node_office "https://github.com/sun7485/union-steel/blob/master/apps/office/src/App.tsx"
click node_office_api "https://github.com/sun7485/union-steel/blob/master/apps/office/src/lib/api.ts"
click node_floor "https://github.com/sun7485/union-steel/blob/master/apps/floor/src/App.tsx"
click node_floor_queue "https://github.com/sun7485/union-steel/blob/master/apps/floor/src/lib/queue.ts"
click node_floor_storage "https://github.com/sun7485/union-steel/blob/master/apps/floor/src/lib/idb.ts"
click node_floor_api "https://github.com/sun7485/union-steel/blob/master/apps/floor/src/lib/api.ts"
click node_api_service "https://github.com/sun7485/union-steel/blob/master/services/api/src/index.ts"
click node_api_routes "https://github.com/sun7485/union-steel/tree/master/services/api/src/routes"
click node_worker "https://github.com/sun7485/union-steel/blob/master/services/worker/src/index.ts"
click node_core "https://github.com/sun7485/union-steel/tree/master/packages/core/src"
click node_imports "https://github.com/sun7485/union-steel/blob/master/packages/core/src/importing.ts"
click node_planning "https://github.com/sun7485/union-steel/blob/master/packages/core/src/schedule.ts"
click node_production "https://github.com/sun7485/union-steel/blob/master/packages/core/src/floor.ts"
click node_materials_quality "https://github.com/sun7485/union-steel/blob/master/packages/core/src/material.ts"
click node_insights "https://github.com/sun7485/union-steel/blob/master/packages/core/src/forecast.ts"
click node_db_client "https://github.com/sun7485/union-steel/blob/master/packages/db/src/client.ts"
click node_db_schema "https://github.com/sun7485/union-steel/blob/master/packages/db/src/schema/index.ts"
click node_office_ai "https://github.com/sun7485/union-steel/blob/master/apps/office/src/screens/UnionAi.tsx"
click node_ai_service "https://github.com/sun7485/union-steel/blob/master/packages/ai/src/service.ts"
click node_mcp "https://github.com/sun7485/union-steel/blob/master/services/api/src/mcp/server.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_office,node_office_api,node_floor,node_floor_queue,node_floor_storage,node_floor_api,node_mcp_client toneBlue
class node_api_service,node_api_routes,node_worker toneAmber
class node_core,node_imports,node_planning,node_production,node_materials_quality,node_insights toneMint
class node_db_client,node_db_schema toneRose
class node_office_ai,node_ai_service,node_mcp,node_office_users,node_floor_users toneIndigo
```

## Components

### User applications

- [Office workspace](https://github.com/sun7485/union-steel/blob/master/apps/office/src/App.tsx): `apps/office/src/App.tsx`
- [Office API client](https://github.com/sun7485/union-steel/blob/master/apps/office/src/lib/api.ts): `apps/office/src/lib/api.ts`
- [Floor app](https://github.com/sun7485/union-steel/blob/master/apps/floor/src/App.tsx): `apps/floor/src/App.tsx`
- [Offline event queue](https://github.com/sun7485/union-steel/blob/master/apps/floor/src/lib/queue.ts): `apps/floor/src/lib/queue.ts`
- [Local queue storage](https://github.com/sun7485/union-steel/blob/master/apps/floor/src/lib/idb.ts): `apps/floor/src/lib/idb.ts`
- [Floor API client](https://github.com/sun7485/union-steel/blob/master/apps/floor/src/lib/api.ts): `apps/floor/src/lib/api.ts`

### API and processing

- [API service](https://github.com/sun7485/union-steel/blob/master/services/api/src/index.ts): `services/api/src/index.ts`
- [Domain endpoints](https://github.com/sun7485/union-steel/tree/master/services/api/src/routes): `services/api/src/routes`
- [Background jobs](https://github.com/sun7485/union-steel/blob/master/services/worker/src/index.ts): `services/worker/src/index.ts`

### Factory domain

- [Domain logic](https://github.com/sun7485/union-steel/tree/master/packages/core/src): `packages/core/src`
- [Import processing](https://github.com/sun7485/union-steel/blob/master/packages/core/src/importing.ts): `packages/core/src/importing.ts`
- [Planning and readiness](https://github.com/sun7485/union-steel/blob/master/packages/core/src/schedule.ts): `packages/core/src/schedule.ts`
- [Production tracking](https://github.com/sun7485/union-steel/blob/master/packages/core/src/floor.ts): `packages/core/src/floor.ts`
- [Materials and quality](https://github.com/sun7485/union-steel/blob/master/packages/core/src/material.ts): `packages/core/src/material.ts`
- [Insights and performance](https://github.com/sun7485/union-steel/blob/master/packages/core/src/forecast.ts): `packages/core/src/forecast.ts`

### Persistence

- [Database client](https://github.com/sun7485/union-steel/blob/master/packages/db/src/client.ts): `packages/db/src/client.ts`
- [Tenant data](https://github.com/sun7485/union-steel/blob/master/packages/db/src/schema/index.ts): `packages/db/src/schema/index.ts`

### AI access

- [Office AI interface](https://github.com/sun7485/union-steel/blob/master/apps/office/src/screens/UnionAi.tsx): `apps/office/src/screens/UnionAi.tsx`
- [AI tools and routing](https://github.com/sun7485/union-steel/blob/master/packages/ai/src/service.ts): `packages/ai/src/service.ts`
- [MCP server](https://github.com/sun7485/union-steel/blob/master/services/api/src/mcp/server.ts): `services/api/src/mcp/server.ts`

### Other components

- **Office staff**
- **Floor staff**
- **MCP client**

## Connections

- Office staff → Office workspace: use
- Floor staff → Floor app: use
- Office workspace → Office API client: requests
- Office API client → API service: calls API
- Floor app → Floor API client: requests
- Floor app → Offline event queue: queues events
- Offline event queue → Local queue storage: persists
- Offline event queue → Floor API client: syncs events
- Floor API client → API service: calls API
- API service → Domain endpoints: dispatches
- Domain endpoints → Domain logic: uses domain logic
- API service → Database client: queries
- Database client → Tenant data: uses schema
- Background jobs → API service: background processing
- Import processing → Domain logic: domain operations
- Office workspace → Office AI interface: opens
- Office AI interface → Office API client: requests AI
- Domain endpoints → AI tools and routing: serves AI tools
- AI tools and routing → Domain logic: uses engines
- MCP client → MCP server: asks tools
- MCP server → AI tools and routing: executes tools
- MCP server → API service: calls endpoints