# jaxkirat/promptops architecture

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

- Interactive diagram: https://gitdiagram.com/jaxkirat/promptops
- Repository: https://github.com/jaxkirat/promptops

## Overview

CodeForge is a multi-agent natural-language-to-code platform. Its main workflow accepts a coding request through the REST API or Gradio workspace, then routes and extracts requirements, generates code and pytest tests, applies execution policy, runs permitted work in a sandbox, and returns a report with real test results. The backend also supplies identity and role enforcement, privacy masking, quotas, run history, and instructor approvals. The graph includes documented features whose implementation was not sampled; those links rely on README statements or source-index references rather than claims of direct source inspection.

Main entry points: [`codeforge/graph/workflow.py`](https://github.com/jaxkirat/promptops/blob/main/codeforge/graph/workflow.py) (LangGraph workflow), [`codeforge/services/run_service.py`](https://github.com/jaxkirat/promptops/blob/main/codeforge/services/run_service.py) (Run service), [`codeforge/api/main.py`](https://github.com/jaxkirat/promptops/blob/main/codeforge/api/main.py) (REST API), [`codeforge/database/database.py`](https://github.com/jaxkirat/promptops/blob/main/codeforge/database/database.py) (Application database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User surfaces"]
  node_fastapi["REST API<br/>[main.py]"]
  node_workspace["Gradio workspace<br/>[app.py]"]
  node_uihandlers["UI callbacks<br/>[handlers.py]"]
  node_adapter["Session adapter<br/>[gradio_adapter.py]"]
end

subgraph group_identity["Identity and controls"]
  node_runservice["Run service<br/>[run_service.py]"]
  node_identitycore["Trusted identity<br/>[identity.py]"]
  node_authservice["Authentication<br/>[auth_service.py]"]
  node_privacy["Privacy masking<br/>[masker.py]"]
  node_quota["Quota service<br/>[quota_service.py]"]
end

subgraph group_generation["Code generation"]
  node_workflow["LangGraph workflow<br/>[workflow.py]"]
  node_router["Request router<br/>[router_agent.py]"]
  node_requirements["Requirements agent"]
  node_codegen["Code generation"]
  node_testgen["Test generation"]
end

subgraph group_execution["Execution and approval"]
  node_policy["AST policy<br/>[policy.py]"]
  node_runner["Execution runner<br/>[runner.py]"]
  node_sandbox["Sandbox backend<br/>[sandbox.py]"]
  node_reporter["Run report<br/>[reporter.py]"]
  node_approval["Instructor approvals"]
end

subgraph group_data["Persistence and SQL"]
  node_database[("Application database<br/>[database.py]")]
  node_sql["SQL workspace service<br/>[service.py]"]
end

node_user(("Requester"))

node_user -->|"submits request"| node_fastapi
node_user -->|"uses workspace"| node_workspace
node_fastapi -->|"delegates runs"| node_runservice
node_workspace -->|"dispatches callbacks"| node_uihandlers
node_uihandlers -->|"uses session"| node_adapter
node_adapter -->|"calls shared services"| node_runservice
node_runservice -->|"resolves identity"| node_identitycore
node_runservice -->|"masks input"| node_privacy
node_runservice -->|"reserves quota"| node_quota
node_fastapi -->|"serves auth routes"| node_authservice
node_authservice -.->|"persists accounts"| node_database
node_runservice -->|"invokes pipeline"| node_workflow
node_workflow -->|"dispatches routing"| node_router
node_workflow -->|"dispatches extraction"| node_requirements
node_workflow -->|"dispatches generation"| node_codegen
node_workflow -->|"dispatches tests"| node_testgen
node_workflow -->|"checks generated code"| node_policy
node_workflow -->|"runs permitted code"| node_runner
node_runner -.->|"executes in"| node_sandbox
node_workflow -.->|"builds result"| node_reporter
node_runservice -->|"stores sanitized runs"| node_database
node_runservice -->|"creates approval"| node_approval
node_approval -->|"resumes graph"| node_workflow
node_fastapi -.->|"routes SQL requests"| node_sql
node_sql -->|"queries scoped data"| node_database

click node_fastapi "https://github.com/jaxkirat/promptops/blob/main/codeforge/api/main.py"
click node_workspace "https://github.com/jaxkirat/promptops/blob/main/codeforge/ui/app.py"
click node_uihandlers "https://github.com/jaxkirat/promptops/blob/main/codeforge/ui/handlers.py"
click node_adapter "https://github.com/jaxkirat/promptops/blob/main/codeforge/integration/gradio_adapter.py"
click node_runservice "https://github.com/jaxkirat/promptops/blob/main/codeforge/services/run_service.py"
click node_identitycore "https://github.com/jaxkirat/promptops/blob/main/codeforge/auth/identity.py"
click node_authservice "https://github.com/jaxkirat/promptops/blob/main/codeforge/services/auth_service.py"
click node_privacy "https://github.com/jaxkirat/promptops/blob/main/codeforge/privacy/masker.py"
click node_quota "https://github.com/jaxkirat/promptops/blob/main/codeforge/services/quota_service.py"
click node_workflow "https://github.com/jaxkirat/promptops/blob/main/codeforge/graph/workflow.py"
click node_router "https://github.com/jaxkirat/promptops/blob/main/codeforge/agents/router_agent.py"
click node_requirements "https://github.com/jaxkirat/promptops/blob/main/codeforge/agents/requirements_agent.py"
click node_codegen "https://github.com/jaxkirat/promptops/blob/main/codeforge/agents/code_generation_agent.py"
click node_testgen "https://github.com/jaxkirat/promptops/blob/main/codeforge/agents/code_generation_agent.py"
click node_policy "https://github.com/jaxkirat/promptops/blob/main/codeforge/execution/policy.py"
click node_runner "https://github.com/jaxkirat/promptops/blob/main/codeforge/execution/runner.py"
click node_sandbox "https://github.com/jaxkirat/promptops/blob/main/codeforge/execution/sandbox.py"
click node_reporter "https://github.com/jaxkirat/promptops/blob/main/codeforge/execution/reporter.py"
click node_approval "https://github.com/jaxkirat/promptops/blob/main/codeforge/services/approval_service.py"
click node_database "https://github.com/jaxkirat/promptops/blob/main/codeforge/database/database.py"
click node_sql "https://github.com/jaxkirat/promptops/blob/main/codeforge/sql_agent/service.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_fastapi,node_workspace,node_uihandlers,node_adapter toneBlue
class node_runservice,node_identitycore,node_authservice,node_privacy,node_quota toneAmber
class node_workflow,node_router,node_requirements,node_codegen,node_testgen,node_user toneMint
class node_policy,node_runner,node_sandbox,node_reporter,node_approval toneRose
class node_database,node_sql toneIndigo
```

## Components

### User surfaces

- [REST API](https://github.com/jaxkirat/promptops/blob/main/codeforge/api/main.py): `codeforge/api/main.py`
- [Gradio workspace](https://github.com/jaxkirat/promptops/blob/main/codeforge/ui/app.py): `codeforge/ui/app.py`
- [UI callbacks](https://github.com/jaxkirat/promptops/blob/main/codeforge/ui/handlers.py): `codeforge/ui/handlers.py`
- [Session adapter](https://github.com/jaxkirat/promptops/blob/main/codeforge/integration/gradio_adapter.py): `codeforge/integration/gradio_adapter.py`

### Identity and controls

- [Run service](https://github.com/jaxkirat/promptops/blob/main/codeforge/services/run_service.py): `codeforge/services/run_service.py`
- [Trusted identity](https://github.com/jaxkirat/promptops/blob/main/codeforge/auth/identity.py): `codeforge/auth/identity.py`
- [Authentication](https://github.com/jaxkirat/promptops/blob/main/codeforge/services/auth_service.py): `codeforge/services/auth_service.py`
- [Privacy masking](https://github.com/jaxkirat/promptops/blob/main/codeforge/privacy/masker.py): `codeforge/privacy/masker.py`
- [Quota service](https://github.com/jaxkirat/promptops/blob/main/codeforge/services/quota_service.py): `codeforge/services/quota_service.py`

### Code generation

- [LangGraph workflow](https://github.com/jaxkirat/promptops/blob/main/codeforge/graph/workflow.py): `codeforge/graph/workflow.py`
- [Request router](https://github.com/jaxkirat/promptops/blob/main/codeforge/agents/router_agent.py): `codeforge/agents/router_agent.py`
- [Requirements agent](https://github.com/jaxkirat/promptops/blob/main/codeforge/agents/requirements_agent.py): `codeforge/agents/requirements_agent.py`
- [Code generation](https://github.com/jaxkirat/promptops/blob/main/codeforge/agents/code_generation_agent.py): `codeforge/agents/code_generation_agent.py`
- [Test generation](https://github.com/jaxkirat/promptops/blob/main/codeforge/agents/code_generation_agent.py): `codeforge/agents/code_generation_agent.py`

### Execution and approval

- [AST policy](https://github.com/jaxkirat/promptops/blob/main/codeforge/execution/policy.py): `codeforge/execution/policy.py`
- [Execution runner](https://github.com/jaxkirat/promptops/blob/main/codeforge/execution/runner.py): `codeforge/execution/runner.py`
- [Sandbox backend](https://github.com/jaxkirat/promptops/blob/main/codeforge/execution/sandbox.py): `codeforge/execution/sandbox.py`
- [Run report](https://github.com/jaxkirat/promptops/blob/main/codeforge/execution/reporter.py): `codeforge/execution/reporter.py`
- [Instructor approvals](https://github.com/jaxkirat/promptops/blob/main/codeforge/services/approval_service.py): `codeforge/services/approval_service.py`

### Persistence and SQL

- [Application database](https://github.com/jaxkirat/promptops/blob/main/codeforge/database/database.py): `codeforge/database/database.py`
- [SQL workspace service](https://github.com/jaxkirat/promptops/blob/main/codeforge/sql_agent/service.py): `codeforge/sql_agent/service.py`

### Other components

- **Requester**

## Connections

- Requester → REST API: submits request
- Requester → Gradio workspace: uses workspace
- REST API → Run service: delegates runs
- Gradio workspace → UI callbacks: dispatches callbacks (evidence: `codeforge/ui/app.py`)
- UI callbacks → Session adapter: uses session (evidence: `codeforge/ui/handlers.py`)
- Session adapter → Run service: calls shared services
- Run service → Trusted identity: resolves identity (evidence: `codeforge/services/run_service.py`)
- Run service → Privacy masking: masks input (evidence: `codeforge/services/run_service.py`)
- Run service → Quota service: reserves quota (evidence: `codeforge/services/run_service.py`)
- REST API → Authentication: serves auth routes (evidence: `codeforge/api/main.py`)
- Authentication → Application database: persists accounts
- Run service → LangGraph workflow: invokes pipeline (evidence: `codeforge/services/run_service.py`)
- LangGraph workflow → Request router: dispatches routing
- LangGraph workflow → Requirements agent: dispatches extraction
- LangGraph workflow → Code generation: dispatches generation
- LangGraph workflow → Test generation: dispatches tests
- LangGraph workflow → AST policy: checks generated code
- LangGraph workflow → Execution runner: runs permitted code
- Execution runner → Sandbox backend: executes in
- LangGraph workflow → Run report: builds result
- Run service → Application database: stores sanitized runs (evidence: `codeforge/services/run_service.py`)
- Run service → Instructor approvals: creates approval (evidence: `codeforge/services/run_service.py`)
- Instructor approvals → LangGraph workflow: resumes graph (evidence: `codeforge/services/approval_service.py`)
- REST API → SQL workspace service: routes SQL requests
- SQL workspace service → Application database: queries scoped data (evidence: `codeforge/sql_agent/service.py`)