# kishoreaarya/arya-os-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/kishoreaarya/arya-os-v2
- Repository: https://github.com/kishoreaarya/arya-os-v2

## Overview

Arya OS is a content-generation backend with a browser-based creator interface and a broader workflow pipeline intended to be orchestrated by n8n. The creator UI submits image/video generation requests and polls job status; the documented pipeline spans trend discovery, content and media creation, approval, publishing, analytics, and learning. The graph also shows execution/provider selection and workflow state as internal layers. Several substantial routes and agents are unsampled, so their capabilities are represented by subsystem nodes without speculative call paths.

Main entry points: [`backend/app/workflows/orchestrator.py`](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/workflows/orchestrator.py) (Workflow orchestration), [`backend/app/services/pipeline_state.py`](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/services/pipeline_state.py) (Workflow state), [`backend/app/services/execution_engine.py`](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/services/execution_engine.py) (Execution engine), [`backend/app/main.py`](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creator["Creator interface"]
  node_creator_ui["Creator UI<br/>[App.tsx]"]
  node_creator_api["Creator API client<br/>[creatorApi.ts]"]
end

subgraph group_api["API and workflow access"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_creator_routes["Creator routes<br/>[creator.py]"]
  node_research_routes["Research routes<br/>[research.py]"]
end

subgraph group_pipeline["Content pipeline"]
  node_trend_service["Trend discovery<br/>[service.py]"]
  node_trend_sources["Trend sources"]
  node_workflow_state["Workflow state<br/>[pipeline_state.py]"]
  node_workflow_engine["Workflow orchestration<br/>[orchestrator.py]"]
  node_shot_execution["Shot execution<br/>[shot_executor.py]"]
  node_video_assembly["Video assembly<br/>[video_assembler.py]"]
  node_agents["Content agents"]
  node_approvals_publishing["Approval and publishing<br/>[approvals.py]"]
  node_analytics_learning["Analytics and learning<br/>[analytics.py]"]
end

subgraph group_execution["Generation execution"]
  node_execution_engine["Execution engine"]
  node_decision_engine["Decision engine<br/>[decision_engine.py]"]
  node_provider_router["Provider routing<br/>[router.py]"]
  node_provider_adapters["Provider adapters"]
  node_validators["Output validators"]
end

subgraph group_data["State and learning"]
  node_workflow_records[("Workflow records<br/>[core.py]")]
  node_database_session["Database session<br/>[session.py]"]
  node_asset_storage["Asset storage"]
  node_event_log["Event log<br/>[log.py]"]
end

node_creator_user(("Creator"))
node_n8n(("n8n"))

node_creator_user -->|"uses"| node_creator_ui
node_creator_ui -->|"requests"| node_creator_api
node_creator_api -->|"calls HTTP"| node_creator_routes
node_fastapi -->|"registers"| node_creator_routes
node_fastapi -->|"registers"| node_research_routes
node_research_routes -->|"calls"| node_trend_service
node_trend_service -->|"queries"| node_trend_sources
node_n8n -.->|"calls services"| node_fastapi
node_n8n -->|"resumes pipeline"| node_workflow_state
node_n8n -->|"advances stages"| node_workflow_state
node_workflow_engine -->|"dispatches"| node_shot_execution
node_workflow_engine -->|"assembles"| node_video_assembly
node_workflow_engine -->|"validates video"| node_validators
node_workflow_engine -->|"uses music agent"| node_agents
node_n8n -.->|"orchestrates stages"| node_agents
node_n8n -.->|"requests decisions"| node_approvals_publishing
node_n8n -.->|"runs learning loop"| node_analytics_learning
node_execution_engine -->|"decides retries"| node_decision_engine
node_execution_engine -->|"executes calls"| node_provider_router
node_execution_engine -->|"validates output"| node_validators
node_provider_router -.->|"routes requests"| node_provider_adapters
node_workflow_state -->|"updates stage"| node_workflow_records
node_workflow_state -->|"records transitions"| node_event_log
node_workflow_engine -->|"uses storage"| node_asset_storage
node_database_session -.->|"provides sessions"| node_workflow_records

click node_creator_ui "https://github.com/kishoreaarya/arya-os-v2/blob/main/frontend/src/App.tsx"
click node_creator_api "https://github.com/kishoreaarya/arya-os-v2/blob/main/frontend/src/api/creatorApi.ts"
click node_fastapi "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/main.py"
click node_creator_routes "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/api/routers/creator.py"
click node_research_routes "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/api/routers/research.py"
click node_trend_service "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/services/trend_sources/service.py"
click node_trend_sources "https://github.com/kishoreaarya/arya-os-v2/tree/main/backend/app/services/trend_sources"
click node_workflow_state "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/services/pipeline_state.py"
click node_workflow_engine "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/workflows/orchestrator.py"
click node_shot_execution "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/workflows/shot_executor.py"
click node_video_assembly "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/workflows/video_assembler.py"
click node_agents "https://github.com/kishoreaarya/arya-os-v2/tree/main/backend/app/agents"
click node_approvals_publishing "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/api/routers/approvals.py"
click node_analytics_learning "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/api/routers/analytics.py"
click node_execution_engine "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/services/execution_engine.py"
click node_decision_engine "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/services/decision_engine.py"
click node_provider_router "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/providers/router.py"
click node_provider_adapters "https://github.com/kishoreaarya/arya-os-v2/tree/main/backend/app/providers"
click node_validators "https://github.com/kishoreaarya/arya-os-v2/tree/main/backend/app/validators"
click node_workflow_records "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/models/core.py"
click node_database_session "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/database/session.py"
click node_asset_storage "https://github.com/kishoreaarya/arya-os-v2/tree/main/backend/app/storage"
click node_event_log "https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/events/log.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_creator_ui,node_creator_api toneBlue
class node_fastapi,node_creator_routes,node_research_routes toneAmber
class node_trend_service,node_trend_sources,node_workflow_state,node_workflow_engine,node_shot_execution,node_video_assembly,node_agents,node_approvals_publishing,node_analytics_learning toneMint
class node_execution_engine,node_decision_engine,node_provider_router,node_provider_adapters,node_validators toneRose
class node_workflow_records,node_database_session,node_asset_storage,node_event_log,node_creator_user,node_n8n toneIndigo
```

## Components

### Creator interface

- [Creator UI](https://github.com/kishoreaarya/arya-os-v2/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Creator API client](https://github.com/kishoreaarya/arya-os-v2/blob/main/frontend/src/api/creatorApi.ts): `frontend/src/api/creatorApi.ts`

### API and workflow access

- [FastAPI app](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/main.py): `backend/app/main.py`
- [Creator routes](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/api/routers/creator.py): `backend/app/api/routers/creator.py`
- [Research routes](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/api/routers/research.py): `backend/app/api/routers/research.py`

### Content pipeline

- [Trend discovery](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/services/trend_sources/service.py): `backend/app/services/trend_sources/service.py`
- [Trend sources](https://github.com/kishoreaarya/arya-os-v2/tree/main/backend/app/services/trend_sources): `backend/app/services/trend_sources`
- [Workflow state](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/services/pipeline_state.py): `backend/app/services/pipeline_state.py`
- [Workflow orchestration](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/workflows/orchestrator.py): `backend/app/workflows/orchestrator.py`
- [Shot execution](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/workflows/shot_executor.py): `backend/app/workflows/shot_executor.py`
- [Video assembly](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/workflows/video_assembler.py): `backend/app/workflows/video_assembler.py`
- [Content agents](https://github.com/kishoreaarya/arya-os-v2/tree/main/backend/app/agents): `backend/app/agents`
- [Approval and publishing](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/api/routers/approvals.py): `backend/app/api/routers/approvals.py`
- [Analytics and learning](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/api/routers/analytics.py): `backend/app/api/routers/analytics.py`

### Generation execution

- [Execution engine](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/services/execution_engine.py): `backend/app/services/execution_engine.py`
- [Decision engine](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/services/decision_engine.py): `backend/app/services/decision_engine.py`
- [Provider routing](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/providers/router.py): `backend/app/providers/router.py`
- [Provider adapters](https://github.com/kishoreaarya/arya-os-v2/tree/main/backend/app/providers): `backend/app/providers`
- [Output validators](https://github.com/kishoreaarya/arya-os-v2/tree/main/backend/app/validators): `backend/app/validators`

### State and learning

- [Workflow records](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/models/core.py): `backend/app/models/core.py`
- [Database session](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/database/session.py): `backend/app/database/session.py`
- [Asset storage](https://github.com/kishoreaarya/arya-os-v2/tree/main/backend/app/storage): `backend/app/storage`
- [Event log](https://github.com/kishoreaarya/arya-os-v2/blob/main/backend/app/events/log.py): `backend/app/events/log.py`

### Other components

- **Creator**
- **n8n**

## Connections

- Creator → Creator UI: uses
- Creator UI → Creator API client: requests (evidence: `frontend/src/App.tsx`)
- Creator API client → Creator routes: calls HTTP (evidence: `frontend/src/api/creatorApi.ts`)
- FastAPI app → Creator routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Research routes: registers (evidence: `backend/app/main.py`)
- Research routes → Trend discovery: calls (evidence: `backend/app/api/routers/research.py`)
- Trend discovery → Trend sources: queries (evidence: `backend/app/services/trend_sources/service.py`)
- n8n → FastAPI app: calls services (evidence: `README.md`)
- n8n → Workflow state: resumes pipeline (evidence: `backend/app/services/pipeline_state.py`)
- n8n → Workflow state: advances stages (evidence: `backend/app/services/pipeline_state.py`)
- Workflow orchestration → Shot execution: dispatches (evidence: `backend/app/workflows/orchestrator.py`)
- Workflow orchestration → Video assembly: assembles (evidence: `backend/app/workflows/orchestrator.py`)
- Workflow orchestration → Output validators: validates video (evidence: `backend/app/workflows/orchestrator.py`)
- Workflow orchestration → Content agents: uses music agent (evidence: `backend/app/workflows/orchestrator.py`)
- n8n → Content agents: orchestrates stages (evidence: `README.md`)
- n8n → Approval and publishing: requests decisions (evidence: `README.md`)
- n8n → Analytics and learning: runs learning loop (evidence: `README.md`)
- Execution engine → Decision engine: decides retries (evidence: `backend/app/services/execution_engine.py`)
- Execution engine → Provider routing: executes calls (evidence: `backend/app/services/execution_engine.py`)
- Execution engine → Output validators: validates output (evidence: `backend/app/services/execution_engine.py`)
- Provider routing → Provider adapters: routes requests (evidence: `backend/app/providers/router.py`)
- Workflow state → Workflow records: updates stage (evidence: `backend/app/services/pipeline_state.py`)
- Workflow state → Event log: records transitions (evidence: `backend/app/services/pipeline_state.py`)
- Workflow orchestration → Asset storage: uses storage (evidence: `backend/app/workflows/orchestrator.py`)
- Database session → Workflow records: provides sessions
