# sabriboulahia42/ins_statistiques architecture

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

- Interactive diagram: https://gitdiagram.com/sabriboulahia42/ins_statistiques
- Repository: https://github.com/sabriboulahia42/ins_statistiques

## Overview

1. **Repo shape**
   - This is a monorepo centered on a statistics platform for INS Tunisia, with three client surfaces and a shared backend/core layer:
     - a Node.js server at the repo root,
     - a Vite/React web dashboard in `WebApp/`,
     - a React Native mobile app in `MobileApp/`.
   - The root also contains deployment docs, legal pages, and generated report artifacts.

2. **Backend and API boundary**
   - The root-level `app.js`, `backend.js`, `proxy.js`, and `ins-api.js` form the server-side entry points and integration layer.
   - This layer is the main boundary between clients and data: it serves application endpoints, mediates API calls, and likely proxies or normalizes upstream INS-related data.
   - `cache-manager.js` suggests backend-side caching to avoid repeatedly recomputing or refetching datasets and exports.

3. **Data storage model**
   - The repository uses file-based JSON data under `data/` as the main application dataset store:
     - `agriculture.json`, `demographics.json`, `industry.json`, `tourism.json`, `trade.json`, `traditional.json`.
   - `data/users.json` indicates user/account state is also persisted locally rather than in an external database.
   - `settings.json` and `Request.xml` suggest additional runtime configuration or request payload artifacts.

4. **Authentication subsystem**
   - The `auth/` folder is a self-contained auth module with `config.js`, `db.js`, `middleware.js`, and `routes.js`.
   - Its role is to handle login/session/token concerns and protect privileged routes, especially the admin dashboard.
   - The web client reflects this split with `AuthContext.jsx` and `ProtectedRoute.jsx`, showing auth is enforced at the UI boundary as well as on the server.

5. **Export/report generation subsystem**
   - `exporter/` is a dedicated multi-format export pipeline with TypeScript implementations for Excel, JSON, PDF, PowerPoint, and Word.
   - `exporter.ts` and `exportUtils.ts` act as orchestration/shared helpers, while `exporter.js` and `shared/core/exporter.js` expose reusable runtime entry points.
   - The generated `.pdf`, `.pptx`, and `.json` files in the repo root indicate exports are first-class outputs, not just transient downloads.

6. **Web application architecture**
   - `WebApp/` is a React + Vite front end, with `src/main.ts` bootstrapping the app and `src/App.jsx` composing the top-level layout.
   - The key user flow is login followed by an admin dashboard in `pages/AdminDashboard.jsx`.
   - The dashboard is split into panels for analytics, users, data management, and settings under `src/components/admin/`, with shared navigation in `DashboardSidebar.jsx`.

7. **Shared web UI components**
   - `shared/components/` contains reusable UI pieces such as `DatasetList.jsx`, `ExportPanel.jsx`, and `StatsCard.jsx`.
   - `shared/core/theme.js` and `shared/core/exporter.js` indicate shared presentation and export logic intended to keep the web experience and root app consistent.
   - This shared layer is the main reuse boundary for dashboard-style UI and export controls.

8. **Mobile application architecture**
   - `MobileApp/` is a React Native client with `App.js` as the entry and `api/client.js` as its API integration point.
   - `screens/HomeScreen.js` and `components/AnimatedCard.js` show a lightweight mobile UI focused on presentation and data access rather than admin workflows.
   - The `macos/` and `windows/` directories are native platform shells for desktop targets, meaning the same JS app can run on macOS and Windows with platform-specific wrappers.

9. **Geographic and external data integration**
   - `geo-adapter.js` suggests a normalization layer for geographic or regional data, likely translating backend datasets into a consistent structure for charts/maps.
   - `ins-api.js` points to an external INS data source or integration contract.
   - Together with `cache-manager.js`, this implies a flow of external data ingestion → normalization → cached server-side access → client consumption.

10. **Static/public-facing assets and legal pages**
   - The root includes `index.html`, `index.css`, `privacy.html`, and `terms.html`, which implies the repo also serves static/public pages alongside the app shell.
   - `WebApp/public/` and `MobileApp` platform assets handle client-specific static resources and icons.

11. **Deployment and platform concerns**
   - `render.yaml`, `DEPLOYMENT_GUIDE.md`, `HF_SETUP.md`, and related docs show the app is designed for managed deployment, likely with a separate backend and front-end build step.
   - `MobileApp/windows/*` and `MobileApp/macos/*` are generated/native project files, so the architecture spans web hosting plus desktop/mobile packaging.
   - The platform boundary is therefore: server/data/export core in Node.js, web dashboard in Vite/React, and mobile/native wrappers for React Native.

12. **High-level data flow**
   - Core flow: datasets in `data/` and external INS integration are processed by the backend and cache layer, exposed through auth-protected endpoints, then consumed by the web admin dashboard and mobile client.
   - Secondary flow: the export subsystem reads the same data model to generate downloadable reports in multiple formats.
   - For an architecture diagram, the main nodes are: clients (WebApp, MobileApp) → auth/API server → data/cache/export subsystems → file-based datasets and external INS source.

Main entry points: [`backend.js`](https://github.com/sabriboulahia42/ins_statistiques/blob/main/backend.js) (Backend API), [`exporter`](https://github.com/sabriboulahia42/ins_statistiques/tree/main/exporter) (Exports), [`auth`](https://github.com/sabriboulahia42/ins_statistiques/tree/main/auth) (Auth module), [`WebApp/src/App.jsx`](https://github.com/sabriboulahia42/ins_statistiques/blob/main/WebApp/src/App.jsx) (Web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Core backend"]
  node_app_js["Server app<br/>node entry<br/>[app.js]"]
  node_backend_js["Backend API<br/>server layer<br/>[backend.js]"]
  node_proxy_js["Proxy<br/>integration<br/>[proxy.js]"]
  node_ins_api_js["INS API<br/>external adapter<br/>[ins-api.js]"]
  node_cache_manager_js["Cache<br/>[cache-manager.js]"]
  node_geo_adapter_js["Geo adapter<br/>normalizer<br/>[geo-adapter.js]"]
  node_auth_module["Auth module<br/>auth subsystem"]
  node_auth_routes["Auth routes<br/>[routes.js]"]
  node_auth_middleware["Auth guard<br/>auth middleware<br/>[middleware.js]"]
  node_exporter_pipeline["Exports<br/>report pipeline"]
  node_exporter_ts["Export core<br/>export orchestration<br/>[exporter.ts]"]
end

subgraph group_web["Web app"]
  node_web_app["Web app<br/>react frontend<br/>[App.jsx]"]
  node_web_main["Web entry<br/>frontend bootstrap<br/>[main.ts]"]
  node_login_page["Login<br/>auth ui<br/>[LoginPage.jsx]"]
  node_admin_dashboard["Dashboard<br/>admin ui<br/>[AdminDashboard.jsx]"]
end

subgraph group_mobile["Mobile app"]
  node_mobile_app["Mobile app<br/>react native app<br/>[App.js]"]
  node_mobile_api["Mobile API<br/>client api<br/>[client.js]"]
end

subgraph group_shared["Shared UI"]
  node_shared_components["Shared UI<br/>ui library"]
  node_shared_exporter["Shared export<br/>shared helper<br/>[exporter.js]"]
end

subgraph group_data["Data store"]
  node_datasets[("Datasets<br/>json store")]
end

node_app_js -->|"boots"| node_backend_js
node_backend_js -->|"secures"| node_auth_module
node_backend_js -->|"caches"| node_cache_manager_js
node_backend_js -->|"normalizes"| node_geo_adapter_js
node_backend_js -->|"exports"| node_exporter_pipeline
node_backend_js -->|"reads/writes"| node_datasets
node_proxy_js -->|"forwards"| node_ins_api_js
node_ins_api_js -->|"feeds"| node_cache_manager_js
node_auth_module -->|"exposes"| node_auth_routes
node_auth_module -->|"enforces"| node_auth_middleware
node_auth_routes -->|"stores users"| node_datasets
node_exporter_pipeline -->|"orchestrates"| node_exporter_ts
node_exporter_pipeline -->|"reuses"| node_shared_exporter
node_exporter_pipeline -->|"reads"| node_datasets
node_web_main -->|"mounts"| node_web_app
node_web_app -->|"routes to"| node_login_page
node_web_app -->|"routes to"| node_admin_dashboard
node_admin_dashboard -->|"uses"| node_shared_components
node_admin_dashboard -->|"depends on"| node_auth_module
node_mobile_app -->|"calls"| node_mobile_api
node_mobile_app -.->|"shares UI"| node_shared_components
node_mobile_api -->|"requests"| node_backend_js
node_shared_exporter -.->|"supports"| node_exporter_pipeline

click node_app_js "https://github.com/sabriboulahia42/ins_statistiques/blob/main/app.js"
click node_backend_js "https://github.com/sabriboulahia42/ins_statistiques/blob/main/backend.js"
click node_proxy_js "https://github.com/sabriboulahia42/ins_statistiques/blob/main/proxy.js"
click node_ins_api_js "https://github.com/sabriboulahia42/ins_statistiques/blob/main/ins-api.js"
click node_cache_manager_js "https://github.com/sabriboulahia42/ins_statistiques/blob/main/cache-manager.js"
click node_geo_adapter_js "https://github.com/sabriboulahia42/ins_statistiques/blob/main/geo-adapter.js"
click node_auth_module "https://github.com/sabriboulahia42/ins_statistiques/tree/main/auth"
click node_auth_routes "https://github.com/sabriboulahia42/ins_statistiques/blob/main/auth/routes.js"
click node_auth_middleware "https://github.com/sabriboulahia42/ins_statistiques/blob/main/auth/middleware.js"
click node_exporter_pipeline "https://github.com/sabriboulahia42/ins_statistiques/tree/main/exporter"
click node_exporter_ts "https://github.com/sabriboulahia42/ins_statistiques/blob/main/exporter/exporter.ts"
click node_web_app "https://github.com/sabriboulahia42/ins_statistiques/blob/main/WebApp/src/App.jsx"
click node_web_main "https://github.com/sabriboulahia42/ins_statistiques/blob/main/WebApp/src/main.ts"
click node_login_page "https://github.com/sabriboulahia42/ins_statistiques/blob/main/WebApp/src/pages/LoginPage.jsx"
click node_admin_dashboard "https://github.com/sabriboulahia42/ins_statistiques/blob/main/WebApp/src/pages/AdminDashboard.jsx"
click node_mobile_app "https://github.com/sabriboulahia42/ins_statistiques/blob/main/MobileApp/App.js"
click node_mobile_api "https://github.com/sabriboulahia42/ins_statistiques/blob/main/MobileApp/api/client.js"
click node_shared_components "https://github.com/sabriboulahia42/ins_statistiques/tree/main/shared/components"
click node_shared_exporter "https://github.com/sabriboulahia42/ins_statistiques/blob/main/shared/core/exporter.js"
click node_datasets "https://github.com/sabriboulahia42/ins_statistiques/tree/main/data"

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_js,node_backend_js,node_proxy_js,node_ins_api_js,node_cache_manager_js,node_geo_adapter_js,node_auth_module,node_auth_routes,node_auth_middleware,node_exporter_pipeline,node_exporter_ts toneBlue
class node_web_app,node_web_main,node_login_page,node_admin_dashboard toneAmber
class node_mobile_app,node_mobile_api toneMint
class node_shared_components,node_shared_exporter toneRose
class node_datasets toneIndigo
```

## Components

### Core backend

Node server, auth, data access, caching, export, and integration layers at the repository root.

- [Server app](https://github.com/sabriboulahia42/ins_statistiques/blob/main/app.js): node entry · Primary Node.js application entry point. · `app.js`
- [Backend API](https://github.com/sabriboulahia42/ins_statistiques/blob/main/backend.js): server layer · Backend orchestration and application endpoint layer. · `backend.js`
- [Proxy](https://github.com/sabriboulahia42/ins_statistiques/blob/main/proxy.js): integration · Request mediation and upstream passthrough layer. · `proxy.js`
- [INS API](https://github.com/sabriboulahia42/ins_statistiques/blob/main/ins-api.js): external adapter · Integration contract for INS data access. · `ins-api.js`
- [Cache](https://github.com/sabriboulahia42/ins_statistiques/blob/main/cache-manager.js): cache layer · Server-side caching for datasets and exports. · `cache-manager.js`
- [Geo adapter](https://github.com/sabriboulahia42/ins_statistiques/blob/main/geo-adapter.js): normalizer · Geographic data normalization for charts or maps. · `geo-adapter.js`
- [Auth module](https://github.com/sabriboulahia42/ins_statistiques/tree/main/auth): auth subsystem · Self-contained authentication and route protection boundary. · `auth`
- [Auth routes](https://github.com/sabriboulahia42/ins_statistiques/blob/main/auth/routes.js): auth routes · Login and session-facing route definitions. · `auth/routes.js`
- [Auth guard](https://github.com/sabriboulahia42/ins_statistiques/blob/main/auth/middleware.js): auth middleware · Server-side route protection and request checks. · `auth/middleware.js`
- [Exports](https://github.com/sabriboulahia42/ins_statistiques/tree/main/exporter): report pipeline · Multi-format report generation subsystem. · `exporter`
- [Export core](https://github.com/sabriboulahia42/ins_statistiques/blob/main/exporter/exporter.ts): export orchestration · Main export orchestration entry in TypeScript. · `exporter/exporter.ts`

### Web app

React/Vite dashboard and its UI/auth composition.

- [Web app](https://github.com/sabriboulahia42/ins_statistiques/blob/main/WebApp/src/App.jsx): react frontend · Vite/React dashboard application. · `WebApp/src/App.jsx`
- [Web entry](https://github.com/sabriboulahia42/ins_statistiques/blob/main/WebApp/src/main.ts): frontend bootstrap · Client bootstrap and app mounting. · `WebApp/src/main.ts`
- [Login](https://github.com/sabriboulahia42/ins_statistiques/blob/main/WebApp/src/pages/LoginPage.jsx): auth ui · Login screen for the web client. · `WebApp/src/pages/LoginPage.jsx`
- [Dashboard](https://github.com/sabriboulahia42/ins_statistiques/blob/main/WebApp/src/pages/AdminDashboard.jsx): admin ui · Primary authenticated admin workspace. · `WebApp/src/pages/AdminDashboard.jsx`

### Mobile app

React Native client and platform wrappers.

- [Mobile app](https://github.com/sabriboulahia42/ins_statistiques/blob/main/MobileApp/App.js): react native app · Cross-platform React Native client. · `MobileApp/App.js`
- [Mobile API](https://github.com/sabriboulahia42/ins_statistiques/blob/main/MobileApp/api/client.js): client api · Mobile-side API client integration. · `MobileApp/api/client.js`

### Shared UI

Reusable UI and shared presentation/export helpers.

- [Shared UI](https://github.com/sabriboulahia42/ins_statistiques/tree/main/shared/components): ui library · Reusable dashboard and data display components. · `shared/components`
- [Shared export](https://github.com/sabriboulahia42/ins_statistiques/blob/main/shared/core/exporter.js): shared helper · Shared export helper used by multiple surfaces. · `shared/core/exporter.js`

### Data store

File-based datasets and runtime state used by the backend.

- [Datasets](https://github.com/sabriboulahia42/ins_statistiques/tree/main/data): json store · File-based application datasets and user state. · `data`

## Connections

- Server app → Backend API: boots · Server entry delegates to backend runtime.
- Backend API → Auth module: secures · Backend uses auth to protect privileged routes.
- Backend API → Cache: caches · Backend reads and stores cached results.
- Backend API → Geo adapter: normalizes · Backend normalizes geographic data for clients.
- Backend API → Exports: exports · Backend feeds data into report generation.
- Backend API → Datasets: reads/writes · Backend persists and retrieves file-based state.
- Proxy → INS API: forwards · Proxy mediates upstream INS access.
- INS API → Cache: feeds · External data is cached after retrieval.
- Auth module → Auth routes: exposes · Auth module publishes login/session routes.
- Auth module → Auth guard: enforces · Auth module protects server endpoints.
- Auth routes → Datasets: stores users · User/account state is backed by local JSON data.
- Exports → Export core: orchestrates · Export subsystem is coordinated by the main exporter entry.
- Exports → Shared export: reuses · Shared export helpers support runtime export flows.
- Exports → Datasets: reads · Exports are generated from the core data model.
- Web entry → Web app: mounts · Frontend bootstrap composes the app shell.
- Web app → Login: routes to · Web app includes login flow.
- Web app → Dashboard: routes to · Authenticated users enter the admin dashboard.
- Dashboard → Shared UI: uses · Dashboard panels reuse shared UI components.
- Dashboard → Auth module: depends on · UI protection mirrors server auth boundary.
- Mobile app → Mobile API: calls · Mobile client consumes backend APIs through a client wrapper.
- Mobile app → Shared UI: shares UI · Mobile surface reuses common presentation patterns conceptually.
- Mobile API → Backend API: requests · Mobile API client targets the backend boundary.
- Shared export → Exports: supports · Shared export helper backs the main export subsystem.