# ahmadsajjad-logix/public-grievance-platform architecture

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

- Interactive diagram: https://gitdiagram.com/ahmadsajjad-logix/public-grievance-platform
- Repository: https://github.com/ahmadsajjad-logix/public-grievance-platform

## Overview

Civic Access is a Streamlit public-grievance preparation platform. A citizen enters a complaint and confirms identity and department; the app routes it using jurisdiction and legal guidance, helps assess supporting evidence, prepares a petition and follow-up materials, then provides filing guidance rather than submitting the complaint. The graph includes documented guidance, offence screening, RTI and analytics capabilities. Several edges rely on the SOURCE INDEX or README because app and workflow excerpts are partial; the archived speech module is shown as unused, not as part of the live workflow.

Main entry points: [`app.py`](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/app.py) (Streamlit app), [`grievance/guidance.py`](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/guidance.py) (Department guides), [`grievance/knowledge.py`](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/knowledge.py) (Jurisdiction routing), [`grievance/agents.py`](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/agents.py) (Workflow stages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Citizen interface"]
  node_app["Streamlit app<br/>[app.py]"]
end

subgraph group_workflow["Case workflow"]
  node_agents["Workflow stages<br/>[agents.py]"]
  node_identity["Identity validation<br/>[identity.py]"]
  node_speech["Archived speech module<br/>[speech.py]"]
end

subgraph group_guidance["Routing and guidance"]
  node_knowledge["Jurisdiction routing<br/>[knowledge.py]"]
  node_catalog["Department directory<br/>[catalog.py]"]
  node_legal["Filing profiles<br/>[legal.py]"]
  node_guidance_module["Department guides<br/>[guidance.py]"]
  node_department_research["Department research"]
  node_sector_research["Sector research<br/>[sector_research.py]"]
  node_reference_library["Local references"]
end

subgraph group_preparation["Filing preparation"]
  node_offences["Offence screening<br/>[offences.py]"]
  node_forms["Form assistance<br/>[forms.py]"]
  node_petitions["Petition builder<br/>[petitions.py]"]
  node_channels["Filing channels<br/>[channels.py]"]
  node_rights["Rights and remedies<br/>[rights.py]"]
  node_rti["RTI guidance<br/>[rti.py]"]
end

subgraph group_state["Case and analytics state"]
  node_storage[("Aggregate storage<br/>[storage.py]")]
end

node_citizen(("Citizen"))
node_official_services["Authority portals"]

node_citizen -->|"enters complaint"| node_app
node_app -->|"runs workflow"| node_agents
node_app -->|"validates identity"| node_identity
node_app -->|"routes complaint"| node_knowledge
node_app -->|"shows filing guide"| node_guidance_module
node_app -->|"offers screening"| node_offences
node_app -->|"shows form help"| node_forms
node_app -->|"shows remedies"| node_rights
node_app -->|"shows channels"| node_channels
node_app -->|"downloads draft"| node_petitions
node_app -->|"offers RTI guidance"| node_rti
node_app -->|"saves aggregates"| node_storage
node_knowledge -->|"checks directory"| node_catalog
node_knowledge -->|"builds guide"| node_guidance_module
node_knowledge -->|"gets filing profile"| node_legal
node_knowledge -->|"retrieves references"| node_reference_library
node_guidance_module -->|"uses departments"| node_catalog
node_guidance_module -->|"loads research"| node_department_research
node_guidance_module -->|"extends profiles"| node_sector_research
node_guidance_module -->|"lists documents"| node_reference_library
node_guidance_module -->|"includes form help"| node_forms
node_catalog -->|"extends directory"| node_sector_research
node_sector_research -->|"uses research helpers"| node_department_research
node_agents -->|"routes case"| node_knowledge
node_agents -->|"builds petition"| node_petitions
node_forms -->|"formats case text"| node_agents
node_app -->|"opens filing links"| node_official_services
node_storage -->|"returns aggregates"| node_app

click node_app "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/app.py"
click node_agents "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/agents.py"
click node_identity "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/identity.py"
click node_knowledge "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/knowledge.py"
click node_catalog "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/catalog.py"
click node_legal "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/legal.py"
click node_guidance_module "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/guidance.py"
click node_department_research "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/department_research.py"
click node_sector_research "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/sector_research.py"
click node_reference_library "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/reference_library.py"
click node_offences "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/offences.py"
click node_forms "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/forms.py"
click node_petitions "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/petitions.py"
click node_channels "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/channels.py"
click node_rights "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/rights.py"
click node_rti "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/rti.py"
click node_storage "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/storage.py"
click node_speech "https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/speech.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_app toneBlue
class node_agents,node_identity,node_speech toneAmber
class node_knowledge,node_catalog,node_legal,node_guidance_module,node_department_research,node_sector_research,node_reference_library toneMint
class node_offences,node_forms,node_petitions,node_channels,node_rights,node_rti toneRose
class node_storage,node_citizen,node_official_services toneIndigo
```

## Components

### Citizen interface

- [Streamlit app](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/app.py): `app.py`

### Case workflow

- [Workflow stages](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/agents.py): `grievance/agents.py`
- [Identity validation](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/identity.py): `grievance/identity.py`
- [Archived speech module](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/speech.py): `grievance/speech.py`

### Routing and guidance

- [Jurisdiction routing](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/knowledge.py): `grievance/knowledge.py`
- [Department directory](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/catalog.py): `grievance/catalog.py`
- [Filing profiles](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/legal.py): `grievance/legal.py`
- [Department guides](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/guidance.py): `grievance/guidance.py`
- [Department research](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/department_research.py): `grievance/department_research.py`
- [Sector research](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/sector_research.py): `grievance/sector_research.py`
- [Local references](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/reference_library.py): `grievance/reference_library.py`

### Filing preparation

- [Offence screening](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/offences.py): `grievance/offences.py`
- [Form assistance](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/forms.py): `grievance/forms.py`
- [Petition builder](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/petitions.py): `grievance/petitions.py`
- [Filing channels](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/channels.py): `grievance/channels.py`
- [Rights and remedies](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/rights.py): `grievance/rights.py`
- [RTI guidance](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/rti.py): `grievance/rti.py`

### Case and analytics state

- [Aggregate storage](https://github.com/ahmadsajjad-logix/public-grievance-platform/blob/main/grievance/storage.py): `grievance/storage.py`

### Other components

- **Citizen**
- **Authority portals**

## Connections

- Citizen → Streamlit app: enters complaint (evidence: `README.md`)
- Streamlit app → Workflow stages: runs workflow (evidence: `app.py`)
- Streamlit app → Identity validation: validates identity (evidence: `app.py`)
- Streamlit app → Jurisdiction routing: routes complaint (evidence: `app.py`)
- Streamlit app → Department guides: shows filing guide (evidence: `app.py`)
- Streamlit app → Offence screening: offers screening (evidence: `app.py`)
- Streamlit app → Form assistance: shows form help (evidence: `app.py`)
- Streamlit app → Rights and remedies: shows remedies (evidence: `app.py`)
- Streamlit app → Filing channels: shows channels (evidence: `app.py`)
- Streamlit app → Petition builder: downloads draft (evidence: `app.py`)
- Streamlit app → RTI guidance: offers RTI guidance (evidence: `app.py`)
- Streamlit app → Aggregate storage: saves aggregates (evidence: `app.py`)
- Jurisdiction routing → Department directory: checks directory (evidence: `grievance/knowledge.py`)
- Jurisdiction routing → Department guides: builds guide (evidence: `grievance/knowledge.py`)
- Jurisdiction routing → Filing profiles: gets filing profile (evidence: `grievance/knowledge.py`)
- Jurisdiction routing → Local references: retrieves references (evidence: `grievance/knowledge.py`)
- Department guides → Department directory: uses departments (evidence: `grievance/guidance.py`)
- Department guides → Department research: loads research (evidence: `grievance/guidance.py`)
- Department guides → Sector research: extends profiles (evidence: `grievance/guidance.py`)
- Department guides → Local references: lists documents (evidence: `grievance/guidance.py`)
- Department guides → Form assistance: includes form help (evidence: `grievance/guidance.py`)
- Department directory → Sector research: extends directory (evidence: `grievance/catalog.py`)
- Sector research → Department research: uses research helpers (evidence: `grievance/sector_research.py`)
- Workflow stages → Jurisdiction routing: routes case (evidence: `grievance/agents.py`)
- Workflow stages → Petition builder: builds petition (evidence: `grievance/agents.py`)
- Form assistance → Workflow stages: formats case text (evidence: `grievance/forms.py`)
- Streamlit app → Authority portals: opens filing links (evidence: `README.md`)
- Aggregate storage → Streamlit app: returns aggregates (evidence: `grievance/storage.py`)
