# ten101111/azs-mobile architecture

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

- Interactive diagram: https://gitdiagram.com/ten101111/azs-mobile
- Repository: https://github.com/ten101111/azs-mobile

## Overview

АЗС Mobile is a corporate-authenticated PWA for finding and analyzing fuel stations, with operational fuel data and an AI analytics assistant. The main user flow is sign-in, then station lookup or analytics; backend routes provide station and operational data, while AI questions pass through scoped SQL generation, validation, and execution. The README also documents maps, staff recommendations, and offline/PWA behavior. Some branches are documented but not represented by sampled implementation files, so their links are shown only where evidence supports them.

Main entry points: [`azs-mobile/backend/main.py`](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/main.py) (API application), [`azs-mobile/backend/ai/pipeline.py`](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/pipeline.py) (Question pipeline), [`azs-mobile/backend/ai/api.py`](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/api.py) (AI API), [`azs-mobile/src/main.jsx`](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/src/main.jsx) (PWA interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile experience"]
  node_app["PWA interface<br/>[main.jsx]"]
  node_orb["AI orb<br/>[AiOrb.jsx]"]
  node_orb_engine["Orb renderer<br/>[orbEngine.js]"]
end

subgraph group_access["Identity and access"]
  node_backend["API application<br/>[main.py]"]
  node_roles["Role scopes<br/>[roles.py]"]
  node_auth_store[("Auth database<br/>[main.py]")]
end

subgraph group_operations["Station operations"]
  node_station_data[("Station registry<br/>[main.py]")]
  node_fuel_stock["Fuel stock<br/>[fuel_stock.py]"]
  node_outages["Fuel outages<br/>[fuel_outages.py]"]
  node_staff["Staff recommendations<br/>[main.py]"]
end

subgraph group_analytics["Analytics and AI"]
  node_summary_api["Summary API<br/>[summary_api.py]"]
  node_summary["KPI summaries<br/>[summary.py]"]
  node_ai_api["AI API<br/>[api.py]"]
  node_pipeline["Question pipeline<br/>[pipeline.py]"]
  node_scope["Scope builder<br/>[scope.py]"]
  node_generator["SQL generator<br/>[generator.py]"]
  node_contract["Data contract<br/>[contract.py]"]
  node_catalog["Schema catalog<br/>[catalog.py]"]
  node_validator["SQL validator<br/>[validator.py]"]
  node_executor["Query executor<br/>[executor.py]"]
  node_journal[("AI journal<br/>[journal.py]")]
  node_dialogs[("AI dialogs<br/>[dialogs.py]")]
  node_quality[("AI quality reviews<br/>[quality.py]")]
  node_quality_export["Quality export<br/>[quality_export.py]"]
end

node_employee(("Employee"))

node_employee -->|"uses"| node_app
node_app -.->|"requests API"| node_backend
node_app -->|"renders"| node_orb
node_orb -->|"creates orb"| node_orb_engine
node_backend -->|"uses roles"| node_roles
node_backend -->|"stores sessions"| node_auth_store
node_backend -->|"serves registry"| node_station_data
node_backend -->|"routes fuel data"| node_fuel_stock
node_backend -->|"routes outage data"| node_outages
node_backend -->|"serves recommendations"| node_staff
node_backend -->|"mounts routes"| node_summary_api
node_summary_api -->|"builds summaries"| node_summary
node_backend -->|"mounts routes"| node_ai_api
node_ai_api -->|"asks question"| node_pipeline
node_pipeline -->|"builds scope"| node_scope
node_pipeline -->|"generates SQL"| node_generator
node_generator -->|"uses prompt contract"| node_contract
node_contract -->|"uses catalog"| node_catalog
node_pipeline -->|"validates SQL"| node_validator
node_pipeline -->|"runs checked SQL"| node_executor
node_pipeline -->|"logs answer"| node_journal
node_ai_api -->|"manages dialogs"| node_dialogs
node_ai_api -->|"records reviews"| node_quality
node_ai_api -->|"exports reviews"| node_quality_export

click node_app "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/src/main.jsx"
click node_orb "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/src/orb/AiOrb.jsx"
click node_orb_engine "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/src/orb/orbEngine.js"
click node_backend "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/main.py"
click node_roles "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/roles.py"
click node_auth_store "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/main.py"
click node_station_data "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/main.py"
click node_fuel_stock "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/fuel_stock.py"
click node_outages "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/fuel_outages.py"
click node_staff "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/main.py"
click node_summary_api "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/summary_api.py"
click node_summary "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/summary.py"
click node_ai_api "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/api.py"
click node_pipeline "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/pipeline.py"
click node_scope "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/scope.py"
click node_generator "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/generator.py"
click node_contract "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/contract.py"
click node_catalog "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/catalog.py"
click node_validator "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/validator.py"
click node_executor "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/executor.py"
click node_journal "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/journal.py"
click node_dialogs "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/dialogs.py"
click node_quality "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/quality.py"
click node_quality_export "https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/quality_export.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,node_orb,node_orb_engine toneBlue
class node_backend,node_roles,node_auth_store toneAmber
class node_station_data,node_fuel_stock,node_outages,node_staff toneMint
class node_summary_api,node_summary,node_ai_api,node_pipeline,node_scope,node_generator,node_contract,node_catalog,node_validator,node_executor,node_journal,node_dialogs,node_quality,node_quality_export toneRose
class node_employee toneIndigo
```

## Components

### Mobile experience

- [PWA interface](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/src/main.jsx): `azs-mobile/src/main.jsx`
- [AI orb](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/src/orb/AiOrb.jsx): `azs-mobile/src/orb/AiOrb.jsx`
- [Orb renderer](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/src/orb/orbEngine.js): `azs-mobile/src/orb/orbEngine.js`

### Identity and access

- [API application](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/main.py): `azs-mobile/backend/main.py`
- [Role scopes](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/roles.py): `azs-mobile/backend/roles.py`
- [Auth database](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/main.py): `azs-mobile/backend/main.py`

### Station operations

- [Station registry](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/main.py): `azs-mobile/backend/main.py`
- [Fuel stock](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/fuel_stock.py): `azs-mobile/backend/fuel_stock.py`
- [Fuel outages](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/fuel_outages.py): `azs-mobile/backend/fuel_outages.py`
- [Staff recommendations](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/main.py): `azs-mobile/backend/main.py`

### Analytics and AI

- [Summary API](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/summary_api.py): `azs-mobile/backend/summary_api.py`
- [KPI summaries](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/summary.py): `azs-mobile/backend/summary.py`
- [AI API](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/api.py): `azs-mobile/backend/ai/api.py`
- [Question pipeline](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/pipeline.py): `azs-mobile/backend/ai/pipeline.py`
- [Scope builder](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/scope.py): `azs-mobile/backend/ai/scope.py`
- [SQL generator](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/generator.py): `azs-mobile/backend/ai/generator.py`
- [Data contract](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/contract.py): `azs-mobile/backend/ai/contract.py`
- [Schema catalog](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/catalog.py): `azs-mobile/backend/ai/catalog.py`
- [SQL validator](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/validator.py): `azs-mobile/backend/ai/validator.py`
- [Query executor](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/executor.py): `azs-mobile/backend/ai/executor.py`
- [AI journal](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/journal.py): `azs-mobile/backend/ai/journal.py`
- [AI dialogs](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/dialogs.py): `azs-mobile/backend/ai/dialogs.py`
- [AI quality reviews](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/quality.py): `azs-mobile/backend/ai/quality.py`
- [Quality export](https://github.com/ten101111/azs-mobile/blob/main/azs-mobile/backend/ai/quality_export.py): `azs-mobile/backend/ai/quality_export.py`

### Other components

- **Employee**

## Connections

- Employee → PWA interface: uses
- PWA interface → API application: requests API
- PWA interface → AI orb: renders (evidence: `azs-mobile/src/main.jsx`)
- AI orb → Orb renderer: creates orb (evidence: `azs-mobile/src/orb/AiOrb.jsx`)
- API application → Role scopes: uses roles (evidence: `azs-mobile/backend/main.py`)
- API application → Auth database: stores sessions (evidence: `azs-mobile/backend/main.py`)
- API application → Station registry: serves registry (evidence: `azs-mobile/backend/main.py`)
- API application → Fuel stock: routes fuel data (evidence: `azs-mobile/backend/main.py`)
- API application → Fuel outages: routes outage data (evidence: `azs-mobile/backend/main.py`)
- API application → Staff recommendations: serves recommendations (evidence: `azs-mobile/backend/main.py`)
- API application → Summary API: mounts routes (evidence: `azs-mobile/backend/main.py`)
- Summary API → KPI summaries: builds summaries (evidence: `azs-mobile/backend/summary_api.py`)
- API application → AI API: mounts routes (evidence: `azs-mobile/backend/main.py`)
- AI API → Question pipeline: asks question (evidence: `azs-mobile/backend/ai/api.py`)
- Question pipeline → Scope builder: builds scope (evidence: `azs-mobile/backend/ai/pipeline.py`)
- Question pipeline → SQL generator: generates SQL (evidence: `azs-mobile/backend/ai/pipeline.py`)
- SQL generator → Data contract: uses prompt contract (evidence: `azs-mobile/backend/ai/generator.py`)
- Data contract → Schema catalog: uses catalog (evidence: `azs-mobile/backend/ai/contract.py`)
- Question pipeline → SQL validator: validates SQL (evidence: `azs-mobile/backend/ai/pipeline.py`)
- Question pipeline → Query executor: runs checked SQL (evidence: `azs-mobile/backend/ai/pipeline.py`)
- Question pipeline → AI journal: logs answer (evidence: `azs-mobile/backend/ai/pipeline.py`)
- AI API → AI dialogs: manages dialogs (evidence: `azs-mobile/backend/ai/api.py`)
- AI API → AI quality reviews: records reviews (evidence: `azs-mobile/backend/ai/api.py`)
- AI API → Quality export: exports reviews (evidence: `azs-mobile/backend/ai/api.py`)
