# sohampawar022005/permitgraph architecture

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

- Interactive diagram: https://gitdiagram.com/sohampawar022005/permitgraph
- Repository: https://github.com/sohampawar022005/permitgraph

## Overview

PermitGraph is regulatory-intelligence and compliance infrastructure, not a government application portal. Its central workflow ingests regulatory text, produces candidate rules for human verification, evaluates verified rules, and relates approvals in a dependency graph; regulatory changes can then be analyzed for impact. The API exposes these capabilities to the web UI and REST-client CLI. The README documents the product pipeline and major capabilities; sampled source confirms selected wiring, including API application workflow and web/CLI API use. Unsampled integrations are not inferred beyond documented relationships.

Main entry points: [`apps/api/app/routers`](https://github.com/sohampawar022005/permitgraph/tree/main/apps/api/app/routers) (REST endpoints), [`packages/graph-engine/graph_engine/graph.py`](https://github.com/sohampawar022005/permitgraph/blob/main/packages/graph-engine/graph_engine/graph.py) (Approval graph), [`apps/api/app/services/change_service.py`](https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/change_service.py) (Change service), [`apps/api/app/services/workflow_service.py`](https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/workflow_service.py) (Application workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Regulatory ingestion"]
  node_regulatory_sources["Regulatory text"]
  node_document_pipeline["Document OCR<br/>[pipeline.py]"]
  node_regulatory_parser["Section extraction<br/>[sections.py]"]
  node_candidate_rules["Rule candidates<br/>[candidates.py]"]
  node_document_service["Document service"]
end

subgraph group_intelligence["Rules and analysis"]
  node_rules_engine["Rules evaluation<br/>[engine.py]"]
  node_rules_service["Rules service<br/>[rules_service.py]"]
  node_approval_graph["Approval graph<br/>[graph.py]"]
  node_graph_storage["Graph adapter<br/>[neo4j_adapter.py]"]
  node_change_detection["Change detection<br/>[diff.py]"]
  node_change_service["Change service<br/>[change_service.py]"]
  node_impact_analysis["Impact analysis<br/>[engine.py]"]
end

subgraph group_operations["Review and workflow"]
  node_human_review["Human verification"]
  node_workflow_service["Application workflow"]
  node_workflow_engine["Workflow and SLA<br/>[workflow.py]"]
end

subgraph group_api["API and persistence"]
  node_audit_models["Audit records<br/>[audit.py]"]
  node_api_routes["REST endpoints"]
  node_api_app["API application<br/>[main.py]"]
  node_database[("Relational database")]
end

subgraph group_clients["User clients"]
  node_web_ui["Web interface<br/>[DiscoverPage.tsx]"]
  node_web_api["Web API client<br/>[api.ts]"]
  node_cli["Operator CLI<br/>[main.py]"]
  node_cli_client["CLI REST client<br/>[client.py]"]
end

node_user(("Operators and users"))

node_regulatory_sources -->|"ingests"| node_document_pipeline
node_document_pipeline -->|"extracts text"| node_regulatory_parser
node_regulatory_parser -->|"produces candidates"| node_candidate_rules
node_candidate_rules -->|"submits for review"| node_human_review
node_human_review -->|"verifies rules"| node_rules_engine
node_rules_engine -->|"supports approvals"| node_approval_graph
node_approval_graph -->|"tracks dependencies"| node_change_detection
node_change_detection -->|"flags affected items"| node_impact_analysis
node_api_app -->|"registers routes"| node_api_routes
node_api_routes -->|"starts and transitions"| node_workflow_service
node_workflow_service -->|"applies transitions"| node_workflow_engine
node_workflow_service -->|"records events"| node_audit_models
node_api_routes -->|"routes review actions"| node_human_review
node_api_routes -->|"reads and writes"| node_database
node_api_app -->|"initializes metadata"| node_database
node_user -->|"uses"| node_web_ui
node_web_ui -->|"requests data"| node_web_api
node_web_api -.->|"calls REST API"| node_api_routes
node_user -->|"uses"| node_cli
node_cli -->|"dispatches commands"| node_cli_client
node_cli_client -->|"calls REST API"| node_api_routes
node_api_routes -.->|"handles documents"| node_document_service
node_api_routes -.->|"serves rules"| node_rules_service
node_api_routes -.->|"handles changes"| node_change_service
node_change_service -.->|"detects changes"| node_change_detection
node_change_service -.->|"analyzes impact"| node_impact_analysis
node_approval_graph -->|"uses adapter"| node_graph_storage

click node_document_pipeline "https://github.com/sohampawar022005/permitgraph/blob/main/packages/document-engine/document_engine/pipeline.py"
click node_regulatory_parser "https://github.com/sohampawar022005/permitgraph/blob/main/packages/regulatory-parser/regulatory_parser/sections.py"
click node_candidate_rules "https://github.com/sohampawar022005/permitgraph/blob/main/packages/regulatory-parser/regulatory_parser/candidates.py"
click node_human_review "https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/verification_service.py"
click node_rules_engine "https://github.com/sohampawar022005/permitgraph/blob/main/packages/rules-engine/rules_engine/engine.py"
click node_rules_service "https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/rules_service.py"
click node_approval_graph "https://github.com/sohampawar022005/permitgraph/blob/main/packages/graph-engine/graph_engine/graph.py"
click node_graph_storage "https://github.com/sohampawar022005/permitgraph/blob/main/packages/graph-engine/graph_engine/adapters/neo4j_adapter.py"
click node_change_detection "https://github.com/sohampawar022005/permitgraph/blob/main/packages/change-detection/change_detection/diff.py"
click node_change_service "https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/change_service.py"
click node_impact_analysis "https://github.com/sohampawar022005/permitgraph/blob/main/packages/impact-analysis/impact_analysis/engine.py"
click node_document_service "https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/document_service.py"
click node_workflow_service "https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/workflow_service.py"
click node_workflow_engine "https://github.com/sohampawar022005/permitgraph/blob/main/packages/workflow-engine/workflow_engine/workflow.py"
click node_audit_models "https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/models/audit.py"
click node_api_routes "https://github.com/sohampawar022005/permitgraph/tree/main/apps/api/app/routers"
click node_api_app "https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/main.py"
click node_web_ui "https://github.com/sohampawar022005/permitgraph/blob/main/apps/web/src/pages/DiscoverPage.tsx"
click node_web_api "https://github.com/sohampawar022005/permitgraph/blob/main/apps/web/src/lib/api.ts"
click node_cli "https://github.com/sohampawar022005/permitgraph/blob/main/cli/permitgraph_cli/main.py"
click node_cli_client "https://github.com/sohampawar022005/permitgraph/blob/main/cli/permitgraph_cli/client.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_regulatory_sources,node_document_pipeline,node_regulatory_parser,node_candidate_rules,node_document_service,node_user toneBlue
class node_rules_engine,node_rules_service,node_approval_graph,node_graph_storage,node_change_detection,node_change_service,node_impact_analysis toneAmber
class node_human_review,node_workflow_service,node_workflow_engine toneMint
class node_audit_models,node_api_routes,node_api_app,node_database toneRose
class node_web_ui,node_web_api,node_cli,node_cli_client toneIndigo
```

## Components

### Regulatory ingestion

- **Regulatory text**
- [Document OCR](https://github.com/sohampawar022005/permitgraph/blob/main/packages/document-engine/document_engine/pipeline.py): `packages/document-engine/document_engine/pipeline.py`
- [Section extraction](https://github.com/sohampawar022005/permitgraph/blob/main/packages/regulatory-parser/regulatory_parser/sections.py): `packages/regulatory-parser/regulatory_parser/sections.py`
- [Rule candidates](https://github.com/sohampawar022005/permitgraph/blob/main/packages/regulatory-parser/regulatory_parser/candidates.py): `packages/regulatory-parser/regulatory_parser/candidates.py`
- [Document service](https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/document_service.py): `apps/api/app/services/document_service.py`

### Rules and analysis

- [Rules evaluation](https://github.com/sohampawar022005/permitgraph/blob/main/packages/rules-engine/rules_engine/engine.py): `packages/rules-engine/rules_engine/engine.py`
- [Rules service](https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/rules_service.py): `apps/api/app/services/rules_service.py`
- [Approval graph](https://github.com/sohampawar022005/permitgraph/blob/main/packages/graph-engine/graph_engine/graph.py): `packages/graph-engine/graph_engine/graph.py`
- [Graph adapter](https://github.com/sohampawar022005/permitgraph/blob/main/packages/graph-engine/graph_engine/adapters/neo4j_adapter.py): `packages/graph-engine/graph_engine/adapters/neo4j_adapter.py`
- [Change detection](https://github.com/sohampawar022005/permitgraph/blob/main/packages/change-detection/change_detection/diff.py): `packages/change-detection/change_detection/diff.py`
- [Change service](https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/change_service.py): `apps/api/app/services/change_service.py`
- [Impact analysis](https://github.com/sohampawar022005/permitgraph/blob/main/packages/impact-analysis/impact_analysis/engine.py): `packages/impact-analysis/impact_analysis/engine.py`

### Review and workflow

- [Human verification](https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/verification_service.py): `apps/api/app/services/verification_service.py`
- [Application workflow](https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/services/workflow_service.py): `apps/api/app/services/workflow_service.py`
- [Workflow and SLA](https://github.com/sohampawar022005/permitgraph/blob/main/packages/workflow-engine/workflow_engine/workflow.py): `packages/workflow-engine/workflow_engine/workflow.py`

### API and persistence

- [Audit records](https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/models/audit.py): `apps/api/app/models/audit.py`
- [REST endpoints](https://github.com/sohampawar022005/permitgraph/tree/main/apps/api/app/routers): `apps/api/app/routers`
- [API application](https://github.com/sohampawar022005/permitgraph/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- **Relational database**

### User clients

- [Web interface](https://github.com/sohampawar022005/permitgraph/blob/main/apps/web/src/pages/DiscoverPage.tsx): `apps/web/src/pages/DiscoverPage.tsx`
- [Web API client](https://github.com/sohampawar022005/permitgraph/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`
- [Operator CLI](https://github.com/sohampawar022005/permitgraph/blob/main/cli/permitgraph_cli/main.py): `cli/permitgraph_cli/main.py`
- [CLI REST client](https://github.com/sohampawar022005/permitgraph/blob/main/cli/permitgraph_cli/client.py): `cli/permitgraph_cli/client.py`

### Other components

- **Operators and users**

## Connections

- Regulatory text → Document OCR: ingests (evidence: `README.md`)
- Document OCR → Section extraction: extracts text (evidence: `README.md`)
- Section extraction → Rule candidates: produces candidates (evidence: `README.md`)
- Rule candidates → Human verification: submits for review (evidence: `README.md`)
- Human verification → Rules evaluation: verifies rules (evidence: `README.md`)
- Rules evaluation → Approval graph: supports approvals (evidence: `README.md`)
- Approval graph → Change detection: tracks dependencies (evidence: `README.md`)
- Change detection → Impact analysis: flags affected items (evidence: `README.md`)
- API application → REST endpoints: registers routes (evidence: `apps/api/app/main.py`)
- REST endpoints → Application workflow: starts and transitions (evidence: `apps/api/app/routers/applications.py`)
- Application workflow → Workflow and SLA: applies transitions (evidence: `apps/api/app/services/workflow_service.py`)
- Application workflow → Audit records: records events (evidence: `apps/api/app/services/workflow_service.py`)
- REST endpoints → Human verification: routes review actions (evidence: `apps/api/app/routers/review.py`)
- REST endpoints → Relational database: reads and writes (evidence: `apps/api/app/routers/applications.py`)
- API application → Relational database: initializes metadata (evidence: `apps/api/app/main.py`)
- Operators and users → Web interface: uses (evidence: `README.md`)
- Web interface → Web API client: requests data (evidence: `apps/web/src/pages/DiscoverPage.tsx`)
- Web API client → REST endpoints: calls REST API
- Operators and users → Operator CLI: uses (evidence: `cli/permitgraph_cli/main.py`)
- Operator CLI → CLI REST client: dispatches commands (evidence: `cli/permitgraph_cli/main.py`)
- CLI REST client → REST endpoints: calls REST API (evidence: `cli/permitgraph_cli/client.py`)
- REST endpoints → Document service: handles documents
- REST endpoints → Rules service: serves rules
- REST endpoints → Change service: handles changes
- Change service → Change detection: detects changes
- Change service → Impact analysis: analyzes impact
- Approval graph → Graph adapter: uses adapter (evidence: `packages/graph-engine/graph_engine/adapters/neo4j_adapter.py`)
