# govtechmy/hansards-front architecture

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

- Interactive diagram: https://gitdiagram.com/govtechmy/hansards-front
- Repository: https://github.com/govtechmy/hansards-front

## Overview

##### Project Type and Purpose
- Full-stack web application (front-end only) built with Next.js and React.
- Purpose: render dashboards, charts, geo-maps, and data catalogs by fetching Hansards data from a separate back-end service.
- Key features: server-side rendering/static generation (SSG/SSR), internationalization, interactive charts/maps, client-side hooks and contexts, and a small internal API layer (Next.js API routes).

##### File Structure and Key Components
a. Presentation Layer
– /pages (Next.js routing: UI pages and API endpoints under /pages/api)
– /components (reusable UI building blocks: Button, Modal, Chart-Header, Map components)
– /dashboards & /data-catalogue (higher-level page compositions)
– /charts (chart primitives: bar, line, heatmap, choropleth, etc.)
– /public & /styles (static assets and CSS/Tailwind styling)
b. Application Logic Layer
– /lib/api.ts (client for BE communication)
– /lib/routes.ts & /lib/schema (route definitions + data schemas)
– /hooks (useData, useCache, useMap, etc.)
– /lib/contexts (analytics, slider, window contexts)
– /pages/api (Next.js serverless endpoints: count, revalidate)
– next.config.js + next‐i18next.config.js (framework configuration + i18n)
c. Data Layer
– External Hansards back-end (NEXT_PUBLIC_API_URL)
– Tinybird analytics endpoint (/lib/tinybird.ts)

##### Architectural Patterns and Design Principles
- File-based routing (Next.js)
- Separation of concerns:
– Presentation (components, charts)
– Data‐fetching (hooks + lib/api)
– State management (React Contexts + hooks)
- Static‐first strategy: heavy use of build‐time JSON imports (geojson)
- API abstraction in lib/api.ts + route definitions in lib/routes.ts
- DRY styling via Tailwind + CSS modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser
    Browser["Browser (User)"]:::browser

    %% Next.js Server
    subgraph "Next.js Server"
        direction TB
        Pages["Pages (SSR/SSG)"]:::next
        APIRoutes["API Routes"]:::next
        Config["Configuration\n(next.config.js,\nnext-i18next.config.js)"]:::next
        subgraph "Client Modules"
            direction TB
            APIClient["lib/api.ts"]:::logic
            Routes["lib/routes.ts"]:::logic
            Schema["lib/schema"]:::logic
            Hooks["hooks"]:::logic
            Contexts["lib/contexts"]:::logic
            TinybirdClient["lib/tinybird.ts"]:::logic
        end
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Components["components/"]:::presentation
        Dashboards["dashboards/"]:::viz
        DataCatalogue["data-catalogue/"]:::viz
        ChartsComp["charts/"]:::viz
    end

    %% Static Assets & Data
    subgraph "Static Assets & Data"
        direction TB
        Public["public/"]:::static
        GeoJSON["lib/geojson/"]:::static
        Env[".env.example"]:::data
    end

    %% External Services
    BE["Hansards-back API"]:::external
    AB["Tinybird Analytics"]:::analytics

    %% Flows
    Browser -->|"Request URL"| Pages
    Pages -->|"GET /hansards"| APIClient
    APIClient -->|"fetch transcripts"| BE
    Pages -->|"import geojson"| GeoJSON
    Browser -->|"Event tracking"| Contexts
    Contexts -->|"send event"| AB
    Browser -->|"POST /count"| APIRoutes
    Browser -->|"POST /revalidate"| APIRoutes
    Pages -->|"serve static"| Public

    %% Cross references
    Pages --> Components
    Pages --> Dashboards
    Pages --> DataCatalogue
    Pages --> ChartsComp
    Config --> Hooks
    Hooks --> APIClient
    Hooks --> GeoJSON
    APIRoutes --> APIClient

    %% Click Events
    click Pages "https://github.com/govtechmy/hansards-front/tree/main/pages/"
    click Components "https://github.com/govtechmy/hansards-front/tree/main/components/"
    click Dashboards "https://github.com/govtechmy/hansards-front/tree/main/dashboards/"
    click DataCatalogue "https://github.com/govtechmy/hansards-front/tree/main/data-catalogue/"
    click ChartsComp "https://github.com/govtechmy/hansards-front/tree/main/charts/"
    click Public "https://github.com/govtechmy/hansards-front/tree/main/public/"
    click GeoJSON "https://github.com/govtechmy/hansards-front/tree/main/lib/geojson/"
    click APIClient "https://github.com/govtechmy/hansards-front/blob/main/lib/api.ts"
    click Routes "https://github.com/govtechmy/hansards-front/blob/main/lib/routes.ts"
    click Schema "https://github.com/govtechmy/hansards-front/tree/main/lib/schema/"
    click Hooks "https://github.com/govtechmy/hansards-front/tree/main/hooks/"
    click Contexts "https://github.com/govtechmy/hansards-front/tree/main/lib/contexts/"
    click TinybirdClient "https://github.com/govtechmy/hansards-front/blob/main/lib/tinybird.ts"
    click Env "https://github.com/govtechmy/hansards-front/blob/main/.env.example"
    click APIRoutes "https://github.com/govtechmy/hansards-front/tree/main/pages/api/"

    %% Styles
    classDef browser fill:#DDDDDD,stroke:#888,stroke-width:1px
    classDef next fill:#D0E6FF,stroke:#339,stroke-width:1px
    classDef logic fill:#E8F1FF,stroke:#339,stroke-width:1px
    classDef presentation fill:#FFF5E6,stroke:#E69500,stroke-width:1px
    classDef viz fill:#FFE6E6,stroke:#E63333,stroke-width:1px
    classDef static fill:#E6FFE6,stroke:#33A833,stroke-width:1px,shape:cylinder
    classDef data fill:#CCFFCC,stroke:#33A833,stroke-width:1px
    classDef external fill:#FFD6D6,stroke:#CC0000,stroke-width:1px
    classDef analytics fill:#F3E6FF,stroke:#8000CC,stroke-width:1px
```
