# iaavas/nepalbynumbers architecture

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

- Interactive diagram: https://gitdiagram.com/iaavas/nepalbynumbers
- Repository: https://github.com/iaavas/nepalbynumbers

## Overview

##### Project Type and Purpose
- Nepal By Numbers is a full-stack, server-rendered web application built with Next.js/React.
- Purpose: Interactive map visualizations of Nepal’s socio-economic data (GDP, HDI, etc.), real-time CSV/Excel imports, theming, and project saving via Firebase.

##### File Structure Analysis
- Top-level:
- app/ – Next.js “app router” pages, server-side API routes, global CSS, layout, and loading/error handlers
- components/ – Two sets: reusable UI primitives (components/ui) and page-specific widgets (app/components)
- context/, hooks/, utils/, constants/ – State management (React Context), custom hooks, utility functions, and constants
- libs/ – Third-party integrations: Firebase setup (libs/firebase) and OpenPixel tracker (lib/openpixel)
- assets/ – Static GeoJSON data for provinces, districts, world map
- public/ – Static images and marketing assets
- next.config.js, tailwind.config.ts, tsconfig.json – Build and style configuration

##### README Insights
- Architecture summary:
- Frontend: Next.js + React + D3.js + Leaflet
- Server/API: Next.js serverless routes under app/api (log-fingerprint, track)
- Database: Firebase (Auth + Firestore/Realtime on projects)
- Styling: Tailwind CSS

a. Main Components
1. Client Browser (User’s UI)
- Next.js pages & React components (app/pages, components/ui, map widgets)
- Context Providers & Hooks (AuthContext, Data hooks)
- D3.js & Leaflet for map rendering
2. Next.js Server (Server-Side Rendering & API Layer)
- SSR/ISR for initial page loads
- Serverless API routes (app/api/log-fingerprint, track)
3. Firebase
- Authentication (login/save projects)
- Firestore/Realtime DB (persist user projects and settings)
4. Static Data Storage
- GeoJSON files in assets/data
5. External Service: OpenPixel
- Usage via lib/openpixel/tracker for analytics/tracking

b. Relationships & Data Flows
- Client → Next.js API → Firebase (CRUD on projects)
- Client directly reads static assets under /assets (districts, provinces JSON)
- Client invokes lib/openpixel/tracker → External OpenPixel endpoint
- SSR fetches initial data (if any) via hooks on server
- React Contexts orchestrate state between UI components

c. Architectural Patterns & Principles
- Separation of Concerns: UI layer, state layer (Contexts/hooks), data layer (API + Firebase), static assets
- File-system routing (Next.js app router)
- Context API for global state
- Serverless functions for “backend” endpoints
- Component-based UI with atomic design (primitives in components/ui, composites in app/components)

d. Key Technologies & Frameworks
- Next.js / React / TypeScript
- Tailwind CSS
- D3.js & Leaflet
- Firebase Auth & Firestore
- OpenPixel analytics
- GitHub Actions / Vercel (implied hosting/CI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser UI Layer
    subgraph "Browser UI" 
        direction TB
        Pages["Next.js Pages"]:::ui
        MapRender["Map Renderer (Leaflet/D3)"]:::ui
        UIPrims["UI Primitives (Atomic)"]:::ui
        LayoutComp["Layout Components"]:::ui
        Contexts["Context Providers"]:::ui
        Hooks["Custom Hooks"]:::ui
    end

    %% Server/API Layer
    subgraph "Server/API" 
        direction TB
        SSR["SSR / ISR"]:::api
        APIRoutes["API Routes"]:::api
    end

    %% Database Layer
    subgraph "Database" 
        direction TB
        Firestore["Firestore DB"]:::data
    end

    %% Static Assets Layer
    subgraph "Static Assets"
        direction TB
        GeoJSON["GeoJSON Data"]:::data
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        OpenPixel["OpenPixel Analytics"]:::external
    end

    %% Connections
    Pages -->|"uses hooks & contexts"| Hooks
    Pages --> Contexts
    Pages --> MapRender
    Pages --> UIPrims
    Pages --> LayoutComp
    Pages -->|"SSR on request"| SSR
    MapRender -->|"load geojson"| GeoJSON
    UIPrims -->|"UI building blocks"| Pages
    Contexts --> Pages
    Hooks --> Pages
    SSR -->|"calls API routes"| APIRoutes
    Pages -->|"GET /api/log-fingerprint\nGET /api/track"| APIRoutes
    APIRoutes -->|"Firestore: CRUD projects"| Firestore
    Pages -->|"OpenPixel.track()"| OpenPixel

    %% Click Events for mapping
    click Pages "https://github.com/iaavas/nepalbynumbers/blob/master/app/page.tsx"
    click Pages "https://github.com/iaavas/nepalbynumbers/blob/master/app/(pages)/dashboard/page.tsx"
    click Pages "https://github.com/iaavas/nepalbynumbers/blob/master/app/(pages)/map/page.tsx"
    click Pages "https://github.com/iaavas/nepalbynumbers/blob/master/app/(pages)/projects/page.tsx"
    click Pages "https://github.com/iaavas/nepalbynumbers/blob/master/app/(pages)/projects/[prjId]/page.tsx"
    click Pages "https://github.com/iaavas/nepalbynumbers/blob/master/app/(pages)/templates/page.tsx"
    click MapRender "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/map/Map.tsx"
    click MapRender "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/map/Legend.tsx"
    click MapRender "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/map/MapControls.tsx"
    click MapRender "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/map/ColorBar.tsx"
    click UIPrims "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/ui/ColorPicker.tsx"
    click UIPrims "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/ui/Collapsibles.tsx"
    click UIPrims "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/ui/CSVPasteComponent.tsx"
    click UIPrims "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/ui/Export.tsx"
    click UIPrims "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/ui/Loader.tsx"
    click UIPrims "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/ui/Sidebar.tsx"
    click UIPrims "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/ui/Theme.tsx"
    click LayoutComp "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/layout/pageLayout.tsx"
    click LayoutComp "https://github.com/iaavas/nepalbynumbers/blob/master/app/components/layout/DynamicContent.tsx"
    click Contexts "https://github.com/iaavas/nepalbynumbers/blob/master/app/context/AuthContext.tsx"
    click Contexts "https://github.com/iaavas/nepalbynumbers/blob/master/app/context/SettingsContext.tsx"
    click Contexts "https://github.com/iaavas/nepalbynumbers/blob/master/app/context/ColorsContext.tsx"
    click Contexts "https://github.com/iaavas/nepalbynumbers/blob/master/app/context/HighlightContext.tsx"
    click Contexts "https://github.com/iaavas/nepalbynumbers/blob/master/app/context/SearchContext.tsx"
    click Contexts "https://github.com/iaavas/nepalbynumbers/blob/master/app/context/ValueContext.tsx"
    click Contexts "https://github.com/iaavas/nepalbynumbers/blob/master/app/context/WatermarkContext.tsx"
    click Contexts "https://github.com/iaavas/nepalbynumbers/blob/master/app/context/PostfixContext.tsx"
    click Contexts "https://github.com/iaavas/nepalbynumbers/blob/master/app/context/ReferenceContext.tsx"
    click Hooks "https://github.com/iaavas/nepalbynumbers/blob/master/app/hooks/useData.tsx"
    click Hooks "https://github.com/iaavas/nepalbynumbers/blob/master/app/hooks/useProjects.tsx"
    click Hooks "https://github.com/iaavas/nepalbynumbers/blob/master/app/hooks/use-user-session.ts"
    click Hooks "https://github.com/iaavas/nepalbynumbers/blob/master/app/hooks/useUser.ts"
    click APIRoutes "https://github.com/iaavas/nepalbynumbers/blob/master/app/api/log-fingerprint/route.ts"
    click APIRoutes "https://github.com/iaavas/nepalbynumbers/blob/master/app/api/track/route.ts"
    click Firestore "https://github.com/iaavas/nepalbynumbers/blob/master/app/libs/firebase/config.ts"
    click Firestore "https://github.com/iaavas/nepalbynumbers/blob/master/app/libs/firebase/auth.ts"
    click Firestore "https://github.com/iaavas/nepalbynumbers/blob/master/app/actions/auth-actions.ts"
    click GeoJSON "https://github.com/iaavas/nepalbynumbers/blob/master/assets/data/nepal-provinces.json"
    click GeoJSON "https://github.com/iaavas/nepalbynumbers/blob/master/assets/data/nepal-districts.json"
    click GeoJSON "https://github.com/iaavas/nepalbynumbers/blob/master/assets/data/world.json"
    click OpenPixel "https://github.com/iaavas/nepalbynumbers/blob/master/lib/openpixel/config.ts"
    click OpenPixel "https://github.com/iaavas/nepalbynumbers/blob/master/lib/openpixel/tracker.ts"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#0366d6,color:#0366d6;
    classDef api fill:#ffe5cc,stroke:#d2691e,color:#d2691e;
    classDef data fill:#e6ffe6,stroke:#2e8b57,color:#2e8b57;
    classDef external fill:#f0e6ff,stroke:#800080,color:#800080;
```
