# kishoreaarya/arya-os architecture

> Architecture diagram of the GitHub repository kishoreaarya/arya-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/kishoreaarya/arya-os
- Repository: https://github.com/kishoreaarya/arya-os

## Overview

Arya OS is a FastAPI-backed AI content-generation platform with a React creator interface and a broader multi-stage content pipeline. The visible creator workflow submits image/video generation requests, polls job status, and displays generated assets; the pipeline also supports trend research, agent stages, validation, approvals, publishing, analytics, and learning. README and source-index references support several subsystem relationships, but many implementation details were not sampled, so those links are omitted rather than inferred.

Main entry points: [`backend/app/workflows/orchestrator.py`](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/workflows/orchestrator.py) (Workflow Orchestrator), [`backend/app/models`](https://github.com/kishoreaarya/arya-os/tree/main/backend/app/models) (Workflow and Media Records), [`frontend/src/App.tsx`](https://github.com/kishoreaarya/arya-os/blob/main/frontend/src/App.tsx) (Creator Interface), [`frontend/src/api/creatorApi.ts`](https://github.com/kishoreaarya/arya-os/blob/main/frontend/src/api/creatorApi.ts) (Creator API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creator["Creator Experience"]
  node_creator_ui["Creator Interface<br/>[App.tsx]"]
  node_creator_api["Creator API Client<br/>[creatorApi.ts]"]
  node_asset_preview["Asset Preview<br/>[AssetPreview.tsx]"]
end

subgraph group_api["API and Workflow"]
  node_fastapi["FastAPI Application<br/>[main.py]"]
  node_creator_routes["Creator Routes<br/>[creator.py]"]
  node_research_routes["Research Routes<br/>[research.py]"]
  node_orchestrator["Workflow Orchestrator<br/>[orchestrator.py]"]
  node_pipeline_state["Pipeline State<br/>[pipeline_state.py]"]
  node_approvals["Approval Checkpoints<br/>[approvals.py]"]
end

subgraph group_production["Content Production"]
  node_agents["Agent Registry<br/>[registry.py]"]
  node_stage_execution["Stage Execution<br/>[stage_executor.py]"]
  node_shot_execution["Shot Execution<br/>[shot_executor.py]"]
  node_video_assembly["Video Assembly<br/>[video_assembler.py]"]
  node_validators["Output Validators"]
end

subgraph group_intelligence["Research and Learning"]
  node_trend_research["Trend Discovery<br/>[service.py]"]
  node_trend_sources["Trend Sources"]
  node_learning["Learning Feedback"]
end

subgraph group_platform["Providers and Records"]
  node_execution_engine["Provider Execution"]
  node_provider_router["Provider Router<br/>[router.py]"]
  node_data_models[("Workflow and Media Records")]
  node_publishing["Publishing Integrations"]
end

node_user(("Creator"))

node_user -->|"uses"| node_creator_ui
node_creator_ui -->|"submits requests"| node_creator_api
node_creator_api -->|"calls generation API"| node_creator_routes
node_creator_routes -.->|"starts workflows"| node_orchestrator
node_orchestrator -->|"dispatches stages"| node_agents
node_orchestrator -->|"executes stages"| node_stage_execution
node_orchestrator -->|"executes shots"| node_shot_execution
node_orchestrator -->|"assembles video"| node_video_assembly
node_orchestrator -->|"tracks progress"| node_pipeline_state
node_execution_engine -->|"routes calls"| node_provider_router
node_execution_engine -->|"validates output"| node_validators
node_research_routes -->|"requests trends"| node_trend_research
node_trend_research -->|"queries sources"| node_trend_sources
node_creator_routes -.->|"records generation"| node_data_models
node_pipeline_state -->|"updates run state"| node_data_models
node_approvals -.->|"stores decisions"| node_data_models
node_publishing -.->|"records published output"| node_data_models
node_learning -.->|"uses performance feedback"| node_data_models
node_creator_ui -->|"renders assets"| node_asset_preview
node_creator_api -->|"checks health"| node_fastapi

click node_creator_ui "https://github.com/kishoreaarya/arya-os/blob/main/frontend/src/App.tsx"
click node_creator_api "https://github.com/kishoreaarya/arya-os/blob/main/frontend/src/api/creatorApi.ts"
click node_asset_preview "https://github.com/kishoreaarya/arya-os/blob/main/frontend/src/components/AssetPreview.tsx"
click node_fastapi "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/main.py"
click node_creator_routes "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/api/routers/creator.py"
click node_research_routes "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/api/routers/research.py"
click node_orchestrator "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/workflows/orchestrator.py"
click node_pipeline_state "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/services/pipeline_state.py"
click node_trend_research "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/services/trend_sources/service.py"
click node_trend_sources "https://github.com/kishoreaarya/arya-os/tree/main/backend/app/services/trend_sources"
click node_agents "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/agents/registry.py"
click node_stage_execution "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/workflows/stage_executor.py"
click node_shot_execution "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/workflows/shot_executor.py"
click node_video_assembly "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/workflows/video_assembler.py"
click node_validators "https://github.com/kishoreaarya/arya-os/tree/main/backend/app/validators"
click node_execution_engine "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/services/execution_engine.py"
click node_provider_router "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/providers/router.py"
click node_data_models "https://github.com/kishoreaarya/arya-os/tree/main/backend/app/models"
click node_learning "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/services/learning_analyzer.py"
click node_approvals "https://github.com/kishoreaarya/arya-os/blob/main/backend/app/api/routers/approvals.py"
click node_publishing "https://github.com/kishoreaarya/arya-os/tree/main/backend/app/platforms"

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,node_asset_preview toneBlue
class node_fastapi,node_creator_routes,node_research_routes,node_orchestrator,node_pipeline_state,node_approvals toneAmber
class node_agents,node_stage_execution,node_shot_execution,node_video_assembly,node_validators toneMint
class node_trend_research,node_trend_sources,node_learning toneRose
class node_execution_engine,node_provider_router,node_data_models,node_publishing,node_user toneIndigo
```

## Components

### Creator Experience

- [Creator Interface](https://github.com/kishoreaarya/arya-os/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Creator API Client](https://github.com/kishoreaarya/arya-os/blob/main/frontend/src/api/creatorApi.ts): `frontend/src/api/creatorApi.ts`
- [Asset Preview](https://github.com/kishoreaarya/arya-os/blob/main/frontend/src/components/AssetPreview.tsx): `frontend/src/components/AssetPreview.tsx`

### API and Workflow

- [FastAPI Application](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/main.py): `backend/app/main.py`
- [Creator Routes](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/api/routers/creator.py): `backend/app/api/routers/creator.py`
- [Research Routes](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/api/routers/research.py): `backend/app/api/routers/research.py`
- [Workflow Orchestrator](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/workflows/orchestrator.py): `backend/app/workflows/orchestrator.py`
- [Pipeline State](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/services/pipeline_state.py): `backend/app/services/pipeline_state.py`
- [Approval Checkpoints](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/api/routers/approvals.py): `backend/app/api/routers/approvals.py`

### Content Production

- [Agent Registry](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/agents/registry.py): `backend/app/agents/registry.py`
- [Stage Execution](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/workflows/stage_executor.py): `backend/app/workflows/stage_executor.py`
- [Shot Execution](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/workflows/shot_executor.py): `backend/app/workflows/shot_executor.py`
- [Video Assembly](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/workflows/video_assembler.py): `backend/app/workflows/video_assembler.py`
- [Output Validators](https://github.com/kishoreaarya/arya-os/tree/main/backend/app/validators): `backend/app/validators`

### Research and Learning

- [Trend Discovery](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/services/trend_sources/service.py): `backend/app/services/trend_sources/service.py`
- [Trend Sources](https://github.com/kishoreaarya/arya-os/tree/main/backend/app/services/trend_sources): `backend/app/services/trend_sources`
- [Learning Feedback](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/services/learning_analyzer.py): `backend/app/services/learning_analyzer.py`

### Providers and Records

- [Provider Execution](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/services/execution_engine.py): `backend/app/services/execution_engine.py`
- [Provider Router](https://github.com/kishoreaarya/arya-os/blob/main/backend/app/providers/router.py): `backend/app/providers/router.py`
- [Workflow and Media Records](https://github.com/kishoreaarya/arya-os/tree/main/backend/app/models): `backend/app/models`
- [Publishing Integrations](https://github.com/kishoreaarya/arya-os/tree/main/backend/app/platforms): `backend/app/platforms`

### Other components

- **Creator**

## Connections

- Creator → Creator Interface: uses
- Creator Interface → Creator API Client: submits requests (evidence: `frontend/src/App.tsx`)
- Creator API Client → Creator Routes: calls generation API (evidence: `frontend/src/api/creatorApi.ts`)
- Creator Routes → Workflow Orchestrator: starts workflows
- Workflow Orchestrator → Agent Registry: dispatches stages (evidence: `backend/app/workflows/orchestrator.py`)
- Workflow Orchestrator → Stage Execution: executes stages (evidence: `backend/app/workflows/orchestrator.py`)
- Workflow Orchestrator → Shot Execution: executes shots (evidence: `backend/app/workflows/orchestrator.py`)
- Workflow Orchestrator → Video Assembly: assembles video (evidence: `backend/app/workflows/orchestrator.py`)
- Workflow Orchestrator → Pipeline State: tracks progress (evidence: `backend/app/workflows/orchestrator.py`)
- Provider Execution → Provider Router: routes calls (evidence: `backend/app/services/execution_engine.py`)
- Provider Execution → Output Validators: validates output (evidence: `backend/app/services/execution_engine.py`)
- Research Routes → Trend Discovery: requests trends (evidence: `backend/app/api/routers/research.py`)
- Trend Discovery → Trend Sources: queries sources (evidence: `backend/app/services/trend_sources/service.py`)
- Creator Routes → Workflow and Media Records: records generation
- Pipeline State → Workflow and Media Records: updates run state (evidence: `backend/app/services/pipeline_state.py`)
- Approval Checkpoints → Workflow and Media Records: stores decisions (evidence: `README.md`)
- Publishing Integrations → Workflow and Media Records: records published output
- Learning Feedback → Workflow and Media Records: uses performance feedback (evidence: `README.md`)
- Creator Interface → Asset Preview: renders assets (evidence: `frontend/src/App.tsx`)
- Creator API Client → FastAPI Application: checks health (evidence: `frontend/src/api/creatorApi.ts`)