# haseebulhaque/apbra architecture

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

- Interactive diagram: https://gitdiagram.com/haseebulhaque/apbra
- Repository: https://github.com/haseebulhaque/apbra

## Overview

APBRA is a bounded Power BI report-generation prototype. A business user creates a case, provides a requirement and optional schema/evidence, clarifies and confirms material meaning, then receives a validated candidate or an explicit blocked/review state. The web app coordinates the workflow; the API provides protected case lifecycle, persistence, model access and private artifacts. The README documents the end-to-end generation stages, while source-index references support selected module links; unsampled implementation details are not inferred.

Main entry points: [`apps/web/src/EnterpriseApp.tsx`](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/EnterpriseApp.tsx) (Case workspace), [`apps/api/src/apbra_api/application.py`](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/application.py) (Application services), [`apps/api/src/apbra_api/api.py`](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/api.py) (API routes), [`apps/api/src/apbra_api/authorization.py`](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/authorization.py) (Case authorization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Business workspace"]
  node_enterprise_app["Case workspace<br/>[EnterpriseApp.tsx]"]
  node_private_cases["Private cases<br/>[privateCases.tsx]"]
  node_web_api["API client<br/>[api.ts]"]
end

subgraph group_pipeline["Report generation"]
  node_schema_ingestion["Schema ingestion<br/>[schemaIngestion.ts]"]
  node_clarification["Clarification<br/>[clarification.ts]"]
  node_confirmed_requirements["Confirmed contract"]
  node_governed_rag["Governed RAG<br/>[rag.ts]"]
  node_report_design["Report design<br/>[foundry.ts]"]
  node_design_normalization["Design normalization"]
  node_guardrails["Design guardrails<br/>[guardrail.ts]"]
  node_powerbi_compiler["PBIP compiler<br/>[genericPowerBI.ts]"]
  node_deployment_guide["Deployment guide<br/>[deploymentGuide.ts]"]
end

subgraph group_server["API and identity"]
  node_api_routes["API routes<br/>[api.py]"]
  node_application_services["Application services<br/>[application.py]"]
  node_authorization["Case authorization<br/>[authorization.py]"]
  node_identity_adapter["OIDC adapter<br/>[oidc_adapter.py]"]
  node_model_provider["Model provider<br/>[model_provider.py]"]
  node_evidence_service["Evidence handling<br/>[evidence.py]"]
end

subgraph group_storage["Persistence and artifacts"]
  node_sql_persistence[("SQL persistence<br/>[persistence.py]")]
  node_private_evidence[("Private evidence store<br/>[evidence.py]")]
  node_private_artifacts[("Private artifact store<br/>[artifacts.py]")]
end

node_business_user(("Business user"))
node_admin_user(("Administrator"))

node_business_user -->|"uses"| node_enterprise_app
node_admin_user -->|"administers"| node_enterprise_app
node_enterprise_app -->|"opens"| node_private_cases
node_enterprise_app -->|"ingests schema"| node_schema_ingestion
node_enterprise_app -->|"coordinates"| node_clarification
node_enterprise_app -->|"confirms meaning"| node_confirmed_requirements
node_enterprise_app -->|"retrieves knowledge"| node_governed_rag
node_enterprise_app -->|"requests design"| node_report_design
node_enterprise_app -->|"normalizes"| node_design_normalization
node_enterprise_app -->|"evaluates"| node_guardrails
node_enterprise_app -->|"compiles candidate"| node_powerbi_compiler
node_enterprise_app -->|"offers guidance"| node_deployment_guide
node_private_cases -->|"calls"| node_web_api
node_web_api -->|"sends requests"| node_api_routes
node_api_routes -->|"dispatches"| node_application_services
node_api_routes -->|"resolves access"| node_authorization
node_api_routes -->|"uses identity"| node_identity_adapter
node_application_services -->|"reads and writes"| node_sql_persistence
node_application_services -->|"requests model calls"| node_model_provider
node_application_services -->|"handles evidence"| node_evidence_service
node_evidence_service -->|"stores evidence"| node_private_evidence
node_application_services -->|"stores candidates"| node_private_artifacts
node_application_services -->|"checks case access"| node_authorization
node_identity_adapter -->|"resolves identity"| node_sql_persistence
node_authorization -->|"queries access"| node_sql_persistence

click node_enterprise_app "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/EnterpriseApp.tsx"
click node_private_cases "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/privateCases.tsx"
click node_web_api "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/api.ts"
click node_schema_ingestion "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/schemaIngestion.ts"
click node_clarification "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/clarification.ts"
click node_confirmed_requirements "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/confirmedRequirements.ts"
click node_governed_rag "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/rag.ts"
click node_report_design "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/foundry.ts"
click node_design_normalization "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/reportDesignNormalization.ts"
click node_guardrails "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/guardrail.ts"
click node_powerbi_compiler "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/genericPowerBI.ts"
click node_deployment_guide "https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/deploymentGuide.ts"
click node_api_routes "https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/api.py"
click node_application_services "https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/application.py"
click node_authorization "https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/authorization.py"
click node_identity_adapter "https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/oidc_adapter.py"
click node_model_provider "https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/model_provider.py"
click node_evidence_service "https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/evidence.py"
click node_sql_persistence "https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/persistence.py"
click node_private_evidence "https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/evidence.py"
click node_private_artifacts "https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/artifacts.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_enterprise_app,node_private_cases,node_web_api,node_business_user toneBlue
class node_schema_ingestion,node_clarification,node_confirmed_requirements,node_governed_rag,node_report_design,node_design_normalization,node_guardrails,node_powerbi_compiler,node_deployment_guide toneAmber
class node_api_routes,node_application_services,node_authorization,node_identity_adapter,node_model_provider,node_evidence_service toneMint
class node_sql_persistence,node_private_evidence,node_private_artifacts toneRose
class node_admin_user toneIndigo
```

## Components

### Business workspace

- [Case workspace](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/EnterpriseApp.tsx): `apps/web/src/EnterpriseApp.tsx`
- [Private cases](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/privateCases.tsx): `apps/web/src/privateCases.tsx`
- [API client](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`

### Report generation

- [Schema ingestion](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/schemaIngestion.ts): `apps/web/src/schemaIngestion.ts`
- [Clarification](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/clarification.ts): `apps/web/src/clarification.ts`
- [Confirmed contract](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/confirmedRequirements.ts): `apps/web/src/confirmedRequirements.ts`
- [Governed RAG](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/rag.ts): `apps/web/src/rag.ts`
- [Report design](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/foundry.ts): `apps/web/src/foundry.ts`
- [Design normalization](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/reportDesignNormalization.ts): `apps/web/src/reportDesignNormalization.ts`
- [Design guardrails](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/guardrail.ts): `apps/web/src/guardrail.ts`
- [PBIP compiler](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/genericPowerBI.ts): `apps/web/src/genericPowerBI.ts`
- [Deployment guide](https://github.com/haseebulhaque/apbra/blob/main/apps/web/src/deploymentGuide.ts): `apps/web/src/deploymentGuide.ts`

### API and identity

- [API routes](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/api.py): `apps/api/src/apbra_api/api.py`
- [Application services](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/application.py): `apps/api/src/apbra_api/application.py`
- [Case authorization](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/authorization.py): `apps/api/src/apbra_api/authorization.py`
- [OIDC adapter](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/oidc_adapter.py): `apps/api/src/apbra_api/oidc_adapter.py`
- [Model provider](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/model_provider.py): `apps/api/src/apbra_api/model_provider.py`
- [Evidence handling](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/evidence.py): `apps/api/src/apbra_api/evidence.py`

### Persistence and artifacts

- [SQL persistence](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/persistence.py): `apps/api/src/apbra_api/persistence.py`
- [Private evidence store](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/evidence.py): `apps/api/src/apbra_api/evidence.py`
- [Private artifact store](https://github.com/haseebulhaque/apbra/blob/main/apps/api/src/apbra_api/artifacts.py): `apps/api/src/apbra_api/artifacts.py`

### Other components

- **Business user**
- **Administrator**

## Connections

- Business user → Case workspace: uses (evidence: `README.md`)
- Administrator → Case workspace: administers (evidence: `README.md`)
- Case workspace → Private cases: opens (evidence: `apps/web/src/EnterpriseApp.tsx`)
- Case workspace → Schema ingestion: ingests schema (evidence: `apps/web/src/EnterpriseApp.tsx`)
- Case workspace → Clarification: coordinates (evidence: `apps/web/src/EnterpriseApp.tsx`)
- Case workspace → Confirmed contract: confirms meaning (evidence: `apps/web/src/EnterpriseApp.tsx`)
- Case workspace → Governed RAG: retrieves knowledge (evidence: `apps/web/src/EnterpriseApp.tsx`)
- Case workspace → Report design: requests design (evidence: `apps/web/src/EnterpriseApp.tsx`)
- Case workspace → Design normalization: normalizes (evidence: `apps/web/src/EnterpriseApp.tsx`)
- Case workspace → Design guardrails: evaluates (evidence: `apps/web/src/EnterpriseApp.tsx`)
- Case workspace → PBIP compiler: compiles candidate (evidence: `apps/web/src/EnterpriseApp.tsx`)
- Case workspace → Deployment guide: offers guidance (evidence: `apps/web/src/EnterpriseApp.tsx`)
- Private cases → API client: calls (evidence: `apps/web/src/privateCases.tsx`)
- API client → API routes: sends requests (evidence: `README.md`)
- API routes → Application services: dispatches (evidence: `apps/api/src/apbra_api/api.py`)
- API routes → Case authorization: resolves access (evidence: `apps/api/src/apbra_api/api.py`)
- API routes → OIDC adapter: uses identity (evidence: `apps/api/src/apbra_api/api.py`)
- Application services → SQL persistence: reads and writes (evidence: `apps/api/src/apbra_api/application.py`)
- Application services → Model provider: requests model calls (evidence: `apps/api/src/apbra_api/application.py`)
- Application services → Evidence handling: handles evidence (evidence: `apps/api/src/apbra_api/application.py`)
- Evidence handling → Private evidence store: stores evidence (evidence: `README.md`)
- Application services → Private artifact store: stores candidates (evidence: `README.md`)
- Application services → Case authorization: checks case access (evidence: `apps/api/src/apbra_api/application.py`)
- OIDC adapter → SQL persistence: resolves identity (evidence: `apps/api/src/apbra_api/oidc_adapter.py`)
- Case authorization → SQL persistence: queries access (evidence: `apps/api/src/apbra_api/authorization.py`)
