# wilson101xx/imd_deprevation architecture

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

- Interactive diagram: https://gitdiagram.com/wilson101xx/imd_deprevation
- Repository: https://github.com/wilson101xx/imd_deprevation

## Overview

##### Project Type & Purpose
- This is a lightweight single-page web application built with Streamlit (front end) and a small backend module in Python.
- It has no internal database; instead it retrieves data on demand from external REST APIs (IMD 2019 endpoints) and displays results to the user.

##### File-Structure Analysis
- Top level:
- `src/imd_streamlit_app.py` – Streamlit UI code
- `src/imd_backend.py` – Data-fetching & processing functions
- Dependencies are declared in `requirements.txt` (streamlit, requests, pandas).
- No build scripts or deployment manifests beyond the Streamlit runtime.

##### Key Architecture Insights from README
- Two-module separation: UI vs. business logic.
- External data source: indicies of Multiple Deprivation API v2019.
- Technology stack: Python 3.10+, Streamlit, REST calls, pandas for processing.

##### Main Components & Their Relationships
a. User’s Browser / Client
- Interacts via HTTP with the Streamlit server on localhost:8501.
b. Streamlit Server (imd_streamlit_app.py)
- Renders UI widgets (postcode input, tabs for stats & descriptions).
- Calls backend functions to fetch and process data.
c. Backend Module (imd_backend.py)
- Defines functions to build API URLs, make HTTP GET requests, parse JSON into pandas DataFrames.
- Contains any data‐validation or transformation logic.
d. External IMD REST APIs
- Two endpoints: deprivation stats lookup and metadata/descriptions.
e. (Optional) Python Runtime & Libraries
- The environment hosting both UI and backend.

Data flow:
[Browser] → HTTP Postcode input → [Streamlit App] → function call → [Backend] → HTTP request → [External API]
← JSON ← [Backend] processes → DataFrame ← [Streamlit App] displays → Browser

##### Architectural Patterns & Design Principles
- Separation of concerns: UI vs. data logic.
- Single process, synchronous RPC‐style calls (Streamlit handles request→response cycle).
- Modular code organization for maintainability and unit testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Components
    Browser["User Browser"]:::client
    UI["imd_streamlit_app.py - UI"]:::ui
    Backend["imd_backend.py - Backend Module"]:::backend
    API["External IMD REST APIs"]:::external
    JSON["JSON Data"]:::data
    DF["pandas DataFrame"]:::data
    Runtime["Python Runtime (v3.10+)"]:::runtime
    Deps["requirements.txt (streamlit, requests, pandas)"]:::docs
    Docs["README.md - Architecture Notes"]:::docs

    %% Layout
    Browser -->|"HTTP Postcode input"| UI
    UI -->|"calls functions"| Backend
    Backend -->|"HTTP GET /postcode"| API
    API -->|"JSON response"| Backend
    Backend -->|"pandas DataFrame"| UI
    UI -->|"renders UI"| Browser

    %% Runtime and Docs
    Runtime --> Deps
    Runtime --> Docs

    %% Click events
    click UI "https://github.com/wilson101xx/imd_deprevation/blob/main/src/imd_streamlit_app.py"
    click Backend "https://github.com/wilson101xx/imd_deprevation/blob/main/src/imd_backend.py"
    click Deps "https://github.com/wilson101xx/imd_deprevation/blob/main/requirments.txt"
    click Docs "https://github.com/wilson101xx/imd_deprevation/blob/main/README.md"

    %% Styles
    classDef client fill:#f0f8ff,stroke:#000,stroke-width:1px
    classDef ui fill:#c6f6d5,stroke:#2f855a,stroke-width:2px
    classDef backend fill:#bee3f8,stroke:#2b6cb0,stroke-width:2px
    classDef external fill:#fed7d7,stroke:#c53030,stroke-width:2px
    classDef data fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,stroke-dasharray: 5 5
    classDef runtime fill:#edf2f7,stroke:#a0aec0,stroke-width:1px
    classDef docs fill:#fefcbf,stroke:#d69e2e,stroke-width:1px
```
