# axiom-digital/mahallen architecture

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

- Interactive diagram: https://gitdiagram.com/axiom-digital/mahallen
- Repository: https://github.com/axiom-digital/mahallen

## Overview

MahallEN is a pilot neighborhood-livability reporting app. Users browse or filter Muğla neighborhoods, choose a report, and view category metrics, evidence and profile suitability; the API currently serves illustrative database seed data rather than the source-backed static dataset. The map separates API/report generation, persistence, and the React experience. README-documented static research data, operator-only Gemini refresh, and frontend five-category scoring are retained. Edges reflect shown calls or README claims; the research workflow has limited runtime wiring in the excerpts.

Main entry points: [`backend/app/api/routes/neighborhoods.py`](https://github.com/axiom-digital/mahallen/blob/main/backend/app/api/routes/neighborhoods.py) (Neighborhood endpoints), [`frontend/src/App.jsx`](https://github.com/axiom-digital/mahallen/blob/main/frontend/src/App.jsx) (Search and report UI), [`backend/app/main.py`](https://github.com/axiom-digital/mahallen/blob/main/backend/app/main.py) (Application startup), [`backend/app/services/seed_service.py`](https://github.com/axiom-digital/mahallen/blob/main/backend/app/services/seed_service.py) (Pilot seed data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_app["Search and report UI<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_dashboard["Report dashboard"]
  node_scorecard["Score charts<br/>[ScoreCard.jsx]"]
  node_web_scoring["Profile scoring<br/>[scoring.mjs]"]
end

subgraph group_api["API and reports"]
  node_api_routes["Neighborhood endpoints<br/>[neighborhoods.py]"]
  node_schemas["Report schemas<br/>[neighborhood.py]"]
  node_ai["Report synthesis<br/>[ai_service.py]"]
  node_seed["Pilot seed data<br/>[seed_service.py]"]
  node_main["Application startup<br/>[main.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_data["Persistence"]
  node_db[("SQL database<br/>[database.py]")]
  node_neighborhood_model["Neighborhood records<br/>[neighborhood.py]"]
  node_cache_model["Report cache records<br/>[report_cache.py]"]
  node_cache_service["Cache operations<br/>[cache_service.py]"]
end

subgraph group_research["Research and scoring"]
  node_backend_scoring["Livability scoring<br/>[scoring_service.py]"]
  node_static_data["Pilot static dataset"]
  node_collection["Research collection"]
  node_prompts["Versioned prompts"]
  node_grounding["Gemini search client"]
end

node_resident(("Neighborhood seeker"))
node_gemini{{"Gemini provider"}}

node_resident -->|"browses"| node_app
node_app -->|"requests data"| node_api_client
node_app -->|"renders"| node_dashboard
node_app -->|"renders charts"| node_scorecard
node_app -->|"normalizes scores"| node_web_scoring
node_api_client -.->|"calls API"| node_api_routes
node_main -->|"registers routes"| node_api_routes
node_main -->|"creates engine"| node_db
node_main -->|"seeds records"| node_seed
node_main -->|"configures app"| node_config
node_api_routes -->|"queries records"| node_neighborhood_model
node_api_routes -->|"validates responses"| node_schemas
node_api_routes -->|"generates report"| node_ai
node_api_routes -->|"reads and writes"| node_cache_service
node_api_routes -->|"checks settings"| node_config
node_cache_service -->|"stores entries"| node_cache_model
node_seed -->|"creates records"| node_neighborhood_model
node_seed -.->|"computes scores"| node_backend_scoring
node_db -->|"reads settings"| node_config
node_ai -.->|"generates live text"| node_gemini
node_collection -.->|"builds pilot data"| node_static_data
node_prompts -.->|"supports research"| node_grounding
node_grounding -.->|"search grounding"| node_gemini
node_static_data -.->|"runtime import pending"| node_api_routes

click node_app "https://github.com/axiom-digital/mahallen/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/axiom-digital/mahallen/blob/main/frontend/src/services/api.js"
click node_dashboard "https://github.com/axiom-digital/mahallen/blob/main/frontend/src/components/ReportDashboard.jsx"
click node_scorecard "https://github.com/axiom-digital/mahallen/blob/main/frontend/src/components/ScoreCard.jsx"
click node_web_scoring "https://github.com/axiom-digital/mahallen/blob/main/frontend/src/scoring.mjs"
click node_api_routes "https://github.com/axiom-digital/mahallen/blob/main/backend/app/api/routes/neighborhoods.py"
click node_schemas "https://github.com/axiom-digital/mahallen/blob/main/backend/app/schemas/neighborhood.py"
click node_ai "https://github.com/axiom-digital/mahallen/blob/main/backend/app/services/ai_service.py"
click node_seed "https://github.com/axiom-digital/mahallen/blob/main/backend/app/services/seed_service.py"
click node_main "https://github.com/axiom-digital/mahallen/blob/main/backend/app/main.py"
click node_db "https://github.com/axiom-digital/mahallen/blob/main/backend/app/core/database.py"
click node_neighborhood_model "https://github.com/axiom-digital/mahallen/blob/main/backend/app/models/neighborhood.py"
click node_cache_model "https://github.com/axiom-digital/mahallen/blob/main/backend/app/models/report_cache.py"
click node_cache_service "https://github.com/axiom-digital/mahallen/blob/main/backend/app/services/cache_service.py"
click node_config "https://github.com/axiom-digital/mahallen/blob/main/backend/app/core/config.py"
click node_backend_scoring "https://github.com/axiom-digital/mahallen/blob/main/backend/app/services/scoring_service.py"
click node_static_data "https://github.com/axiom-digital/mahallen/tree/main/data/neighborhoods"
click node_collection "https://github.com/axiom-digital/mahallen/blob/main/backend/scripts/collect_direct_sample.py"
click node_prompts "https://github.com/axiom-digital/mahallen/blob/main/backend/scripts/prepare_pilot_prompts.py"
click node_grounding "https://github.com/axiom-digital/mahallen/blob/main/backend/scripts/grounding_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_app,node_api_client,node_dashboard,node_scorecard,node_web_scoring toneBlue
class node_api_routes,node_schemas,node_ai,node_seed,node_main,node_config toneAmber
class node_db,node_neighborhood_model,node_cache_model,node_cache_service toneMint
class node_backend_scoring,node_static_data,node_collection,node_prompts,node_grounding toneRose
class node_resident,node_gemini toneIndigo
```

## Components

### Web experience

- [Search and report UI](https://github.com/axiom-digital/mahallen/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/axiom-digital/mahallen/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Report dashboard](https://github.com/axiom-digital/mahallen/blob/main/frontend/src/components/ReportDashboard.jsx): `frontend/src/components/ReportDashboard.jsx`
- [Score charts](https://github.com/axiom-digital/mahallen/blob/main/frontend/src/components/ScoreCard.jsx): `frontend/src/components/ScoreCard.jsx`
- [Profile scoring](https://github.com/axiom-digital/mahallen/blob/main/frontend/src/scoring.mjs): `frontend/src/scoring.mjs`

### API and reports

- [Neighborhood endpoints](https://github.com/axiom-digital/mahallen/blob/main/backend/app/api/routes/neighborhoods.py): `backend/app/api/routes/neighborhoods.py`
- [Report schemas](https://github.com/axiom-digital/mahallen/blob/main/backend/app/schemas/neighborhood.py): `backend/app/schemas/neighborhood.py`
- [Report synthesis](https://github.com/axiom-digital/mahallen/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Pilot seed data](https://github.com/axiom-digital/mahallen/blob/main/backend/app/services/seed_service.py): `backend/app/services/seed_service.py`
- [Application startup](https://github.com/axiom-digital/mahallen/blob/main/backend/app/main.py): `backend/app/main.py`
- [Runtime configuration](https://github.com/axiom-digital/mahallen/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Persistence

- [SQL database](https://github.com/axiom-digital/mahallen/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Neighborhood records](https://github.com/axiom-digital/mahallen/blob/main/backend/app/models/neighborhood.py): `backend/app/models/neighborhood.py`
- [Report cache records](https://github.com/axiom-digital/mahallen/blob/main/backend/app/models/report_cache.py): `backend/app/models/report_cache.py`
- [Cache operations](https://github.com/axiom-digital/mahallen/blob/main/backend/app/services/cache_service.py): `backend/app/services/cache_service.py`

### Research and scoring

- [Livability scoring](https://github.com/axiom-digital/mahallen/blob/main/backend/app/services/scoring_service.py): `backend/app/services/scoring_service.py`
- [Pilot static dataset](https://github.com/axiom-digital/mahallen/tree/main/data/neighborhoods): `data/neighborhoods`
- [Research collection](https://github.com/axiom-digital/mahallen/blob/main/backend/scripts/collect_direct_sample.py): `backend/scripts/collect_direct_sample.py`
- [Versioned prompts](https://github.com/axiom-digital/mahallen/blob/main/backend/scripts/prepare_pilot_prompts.py): `backend/scripts/prepare_pilot_prompts.py`
- [Gemini search client](https://github.com/axiom-digital/mahallen/blob/main/backend/scripts/grounding_client.py): `backend/scripts/grounding_client.py`

### Other components

- **Neighborhood seeker**
- **Gemini provider**

## Connections

- Neighborhood seeker → Search and report UI: browses (evidence: `README.md`)
- Search and report UI → API client: requests data (evidence: `frontend/src/App.jsx`)
- Search and report UI → Report dashboard: renders (evidence: `frontend/src/App.jsx`)
- Search and report UI → Score charts: renders charts (evidence: `frontend/src/App.jsx`)
- Search and report UI → Profile scoring: normalizes scores (evidence: `frontend/src/App.jsx`)
- API client → Neighborhood endpoints: calls API
- Application startup → Neighborhood endpoints: registers routes (evidence: `backend/app/main.py`)
- Application startup → SQL database: creates engine (evidence: `backend/app/main.py`)
- Application startup → Pilot seed data: seeds records (evidence: `backend/app/main.py`)
- Application startup → Runtime configuration: configures app (evidence: `backend/app/main.py`)
- Neighborhood endpoints → Neighborhood records: queries records (evidence: `backend/app/api/routes/neighborhoods.py`)
- Neighborhood endpoints → Report schemas: validates responses (evidence: `backend/app/api/routes/neighborhoods.py`)
- Neighborhood endpoints → Report synthesis: generates report (evidence: `backend/app/api/routes/neighborhoods.py`)
- Neighborhood endpoints → Cache operations: reads and writes (evidence: `backend/app/api/routes/neighborhoods.py`)
- Neighborhood endpoints → Runtime configuration: checks settings (evidence: `backend/app/api/routes/neighborhoods.py`)
- Cache operations → Report cache records: stores entries (evidence: `backend/app/services/cache_service.py`)
- Pilot seed data → Neighborhood records: creates records (evidence: `backend/app/services/seed_service.py`)
- Pilot seed data → Livability scoring: computes scores (evidence: `backend/app/services/seed_service.py`)
- SQL database → Runtime configuration: reads settings (evidence: `backend/app/core/database.py`)
- Report synthesis → Gemini provider: generates live text (evidence: `backend/app/services/ai_service.py`)
- Research collection → Pilot static dataset: builds pilot data
- Versioned prompts → Gemini search client: supports research
- Gemini search client → Gemini provider: search grounding (evidence: `README.md`)
- Pilot static dataset → Neighborhood endpoints: runtime import pending (evidence: `README.md`)