# mehulsri07/stratadesk architecture

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

- Interactive diagram: https://gitdiagram.com/mehulsri07/stratadesk
- Repository: https://github.com/mehulsri07/stratadesk

## Overview

1. **What this repo is**
   - StrataDesk is a borewell strata visualization system.
   - It is split into three architectural boundaries: a React frontend, an Express/PostgreSQL backend, and a Docker/nginx deployment layer.

2. **Top-level runtime layout**
   - In production Docker mode, traffic enters **nginx** on port 3000.
   - nginx serves the built frontend and forwards `/api/*` requests to the backend service.
   - The backend runs on port 3001 and talks to PostgreSQL on port 5432.

3. **Frontend subsystem**
   - `src/` is a Vite + React + TypeScript application styled with Tailwind.
   - The app is organized around two main pages: a **map/dashboard view** and a **borewell import view**.
   - `src/main.tsx` boots the app; `src/App.tsx` wires the page shell and shared UI.

4. **Frontend UI composition**
   - The UI is broken into reusable panels and layout components: top bar, sidebars, drawers, cards, and toast notifications.
   - `src/components/panels`, `dashboard`, and `map` hold the main screen composition pieces.
   - This suggests a workspace-style interface rather than a simple form-based app.

5. **Visualization domain layer**
   - The core product logic is in `src/components/CrossSection` and `src/lib/crossSectionEngine.ts`.
   - These modules compute and render geological cross-sections, including interpolation and geo utility calculations.
   - `src/components/charts` and `src/components/map` separate chart rendering from geographic map rendering, indicating multiple coordinated views of the same borewell data.

6. **Client state and shared types**
   - `src/store/AppContext.tsx` provides shared app-level state across pages and panels.
   - `src/types` and `src/lib/utils.ts` centralize the domain model and helpers so map, charts, and import flows operate on consistent borewell/strata types.
   - This keeps the visualization and editing surfaces aligned on one data contract.

7. **Backend API subsystem**
   - `backend/` is an Express REST API.
   - `backend/src/routes/borewellRoutes.js` defines the API surface, and `backend/src/controllers/borewellController.js` contains request handling and business logic.
   - `backend/src/app.js` wires middleware and routes; `backend/server.js` is the process entrypoint.

8. **Database access boundary**
   - `backend/src/db/pool.js` and `backend/src/db/init.js` manage PostgreSQL connectivity and bootstrap behavior.
   - The backend owns all direct database interaction; the frontend does not access Postgres directly.
   - This cleanly separates visualization/UI concerns from persistence and query logic.

9. **Schema and initialization**
   - `database/init.sql` holds the initial PostgreSQL schema and seed/bootstrap structure.
   - The repo is designed so the database can be created from scratch either by Docker Compose or by running against a local Postgres instance.
   - The included `.env.example` shows the backend can use either a full `DATABASE_URL` or individual DB connection parameters.

10. **Import/data ingestion flow**
   - The presence of `src/pages/BorewellImportPage.tsx` and the spreadsheet file `IPL Dewa Road 6.xlsx` indicates a domain-specific import workflow.
   - Data likely enters through the frontend import page, is validated/transformed on the client and/or server, and then stored in PostgreSQL for later map and cross-section visualization.

11. **Deployment and orchestration**
   - `docker-compose.yml` coordinates the full stack: database first, then API, then nginx/frontend.
   - `backend/Dockerfile` and `nginx/Dockerfile` indicate separate container boundaries for application logic and static delivery.
   - `railway.toml` shows the stack is also intended for Railway deployment, with the frontend/nginx layer pointing at the API upstream.

12. **Tooling and build boundaries**
   - The frontend build path is Vite + TypeScript + Tailwind, with ESLint/PostCSS/Tailwind configuration at the repo root.
   - The backend has its own Node package and lockfile, so frontend and backend are independently built and deployed.
   - `vite.config.ts` likely provides local `/api` proxying so development mirrors production request routing without nginx.

Overall, the architecture is a classic three-tier setup: a rich client-side visualization app, a thin REST API, and PostgreSQL persistence, with nginx/Docker providing the deployment and routing boundary between them.

Main entry points: [`src/pages/MapDashboardPage.tsx`](https://github.com/mehulsri07/stratadesk/blob/main/src/pages/MapDashboardPage.tsx) (Pages), [`src/main.tsx`](https://github.com/mehulsri07/stratadesk/blob/main/src/main.tsx) (App shell), [`backend/src/app.js`](https://github.com/mehulsri07/stratadesk/blob/main/backend/src/app.js) (API app), [`docker-compose.yml`](https://github.com/mehulsri07/stratadesk/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_shell["App shell<br/>React app<br/>[main.tsx]"]
  node_frontend_pages["Pages<br/>routing views"]
  node_app_context["App state<br/>client store<br/>[AppContext.tsx]"]
  node_ui_panels["Panels<br/>layout UI<br/>[LeftSidebar.tsx]"]
  node_topbar["Top bar<br/>chrome component<br/>[TopBar.tsx]"]
  node_dashboard_ui["Dashboard<br/>screen UI"]
  node_map_view["Map view<br/>geo view<br/>[StrataMap.tsx]"]
  node_import_page["Import flow<br/>ingest UI"]
  node_cross_section["Cross-section<br/>domain viz"]
  node_cross_engine["Engine<br/>geometry logic"]
  node_chart_views["Charts<br/>data viz<br/>[StrataChart.tsx]"]
  node_shared_types["Models<br/>domain types<br/>[models.ts]"]
  node_api_client["API client<br/>HTTP client<br/>[api.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_app["API app<br/>Express app<br/>[app.js]"]
  node_borewell_api["Borewell API<br/>REST routes<br/>[borewellRoutes.js]"]
  node_borewell_logic["Controller<br/>request logic"]
  node_db_pool["DB pool<br/>postgres client<br/>[pool.js]"]
  node_db_init["DB init<br/>bootstrap<br/>[init.js]"]
  node_postgres[("PostgreSQL<br/>data store<br/>[init.sql]")]
end

subgraph group_deploy["Deployment"]
  node_nginx["nginx<br/>reverse proxy<br/>[nginx.conf]"]
  node_compose["Compose<br/>orchestration<br/>[docker-compose.yml]"]
end

node_compose -->|"runs"| node_nginx
node_compose -->|"runs"| node_backend_app
node_compose -->|"starts"| node_postgres
node_nginx -->|"serves"| node_frontend_shell
node_nginx -->|"proxies /api"| node_backend_app
node_frontend_shell -->|"renders"| node_frontend_pages
node_frontend_shell -->|"includes"| node_topbar
node_frontend_shell -->|"provides"| node_app_context
node_frontend_pages -->|"composes"| node_ui_panels
node_frontend_pages -->|"shows"| node_dashboard_ui
node_frontend_pages -->|"shows"| node_map_view
node_frontend_pages -->|"routes to"| node_import_page
node_dashboard_ui -->|"uses"| node_cross_section
node_cross_section -->|"depends on"| node_cross_engine
node_cross_section -->|"uses"| node_shared_types
node_chart_views -->|"uses"| node_shared_types
node_map_view -->|"uses"| node_shared_types
node_api_client -->|"calls"| node_backend_app
node_backend_app -->|"mounts"| node_borewell_api
node_borewell_api -->|"delegates"| node_borewell_logic
node_borewell_logic -->|"queries"| node_db_pool
node_db_init -->|"initializes"| node_postgres
node_db_pool -->|"connects to"| node_postgres

click node_nginx "https://github.com/mehulsri07/stratadesk/blob/main/nginx/nginx.conf"
click node_compose "https://github.com/mehulsri07/stratadesk/blob/main/docker-compose.yml"
click node_frontend_shell "https://github.com/mehulsri07/stratadesk/blob/main/src/main.tsx"
click node_frontend_pages "https://github.com/mehulsri07/stratadesk/blob/main/src/pages/MapDashboardPage.tsx"
click node_app_context "https://github.com/mehulsri07/stratadesk/blob/main/src/store/AppContext.tsx"
click node_ui_panels "https://github.com/mehulsri07/stratadesk/blob/main/src/components/panels/LeftSidebar.tsx"
click node_topbar "https://github.com/mehulsri07/stratadesk/blob/main/src/components/TopBar.tsx"
click node_dashboard_ui "https://github.com/mehulsri07/stratadesk/blob/main/src/components/dashboard/DashboardHeader.tsx"
click node_map_view "https://github.com/mehulsri07/stratadesk/blob/main/src/components/map/StrataMap.tsx"
click node_import_page "https://github.com/mehulsri07/stratadesk/blob/main/src/pages/BorewellImportPage.tsx"
click node_cross_section "https://github.com/mehulsri07/stratadesk/blob/main/src/components/CrossSection/CrossSectionView.tsx"
click node_cross_engine "https://github.com/mehulsri07/stratadesk/blob/main/src/lib/crossSectionEngine.ts"
click node_chart_views "https://github.com/mehulsri07/stratadesk/blob/main/src/components/charts/StrataChart.tsx"
click node_shared_types "https://github.com/mehulsri07/stratadesk/blob/main/src/types/models.ts"
click node_api_client "https://github.com/mehulsri07/stratadesk/blob/main/src/lib/api.ts"
click node_backend_app "https://github.com/mehulsri07/stratadesk/blob/main/backend/src/app.js"
click node_borewell_api "https://github.com/mehulsri07/stratadesk/blob/main/backend/src/routes/borewellRoutes.js"
click node_borewell_logic "https://github.com/mehulsri07/stratadesk/blob/main/backend/src/controllers/borewellController.js"
click node_db_pool "https://github.com/mehulsri07/stratadesk/blob/main/backend/src/db/pool.js"
click node_db_init "https://github.com/mehulsri07/stratadesk/blob/main/backend/src/db/init.js"
click node_postgres "https://github.com/mehulsri07/stratadesk/blob/main/database/init.sql"

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_frontend_shell,node_frontend_pages,node_app_context,node_ui_panels,node_topbar,node_dashboard_ui,node_map_view,node_import_page,node_cross_section,node_cross_engine,node_chart_views,node_shared_types,node_api_client toneBlue
class node_backend_app,node_borewell_api,node_borewell_logic,node_db_pool,node_db_init,node_postgres toneAmber
class node_nginx,node_compose toneMint
```

## Components

### Frontend

React/Vite client for visualization and import workflows

- [App shell](https://github.com/mehulsri07/stratadesk/blob/main/src/main.tsx): React app · Bootstraps the client and wires the shared page shell · `src/main.tsx`
- [Pages](https://github.com/mehulsri07/stratadesk/blob/main/src/pages/MapDashboardPage.tsx): routing views · Primary map/dashboard and borewell import screens · `src/pages/MapDashboardPage.tsx`
- [App state](https://github.com/mehulsri07/stratadesk/blob/main/src/store/AppContext.tsx): client store · Shared application state across panels and pages · `src/store/AppContext.tsx`
- [Panels](https://github.com/mehulsri07/stratadesk/blob/main/src/components/panels/LeftSidebar.tsx): layout UI · Workspace layout pieces such as sidebars, drawers, and panels · `src/components/panels/LeftSidebar.tsx`
- [Top bar](https://github.com/mehulsri07/stratadesk/blob/main/src/components/TopBar.tsx): chrome component · Global app header and navigation chrome · `src/components/TopBar.tsx`
- [Dashboard](https://github.com/mehulsri07/stratadesk/blob/main/src/components/dashboard/DashboardHeader.tsx): screen UI · Dashboard composition for borewell cards and section navigation · `src/components/dashboard/DashboardHeader.tsx`
- [Map view](https://github.com/mehulsri07/stratadesk/blob/main/src/components/map/StrataMap.tsx): geo view · Spatial strata visualization on the dashboard · `src/components/map/StrataMap.tsx`
- [Import flow](https://github.com/mehulsri07/stratadesk/blob/main/src/pages/BorewellImportPage.tsx): ingest UI · Borewell import surface for spreadsheet-driven data entry · `src/pages/BorewellImportPage.tsx`
- [Cross-section](https://github.com/mehulsri07/stratadesk/blob/main/src/components/CrossSection/CrossSectionView.tsx): domain viz · Geological cross-section rendering and interpretation · `src/components/CrossSection/CrossSectionView.tsx`
- [Engine](https://github.com/mehulsri07/stratadesk/blob/main/src/lib/crossSectionEngine.ts): geometry logic · Interpolation and geo utilities for cross-section calculations · `src/lib/crossSectionEngine.ts`
- [Charts](https://github.com/mehulsri07/stratadesk/blob/main/src/components/charts/StrataChart.tsx): data viz · Chart-based strata and cross-section presentations · `src/components/charts/StrataChart.tsx`
- [Models](https://github.com/mehulsri07/stratadesk/blob/main/src/types/models.ts): domain types · Shared borewell and strata contracts used across client features · `src/types/models.ts`
- [API client](https://github.com/mehulsri07/stratadesk/blob/main/src/lib/api.ts): HTTP client · Frontend request layer for backend interactions · `src/lib/api.ts`

### Backend

Express API and PostgreSQL access layer

- [API app](https://github.com/mehulsri07/stratadesk/blob/main/backend/src/app.js): Express app · Configures middleware and mounts REST routes · `backend/src/app.js`
- [Borewell API](https://github.com/mehulsri07/stratadesk/blob/main/backend/src/routes/borewellRoutes.js): REST routes · HTTP surface for borewell data operations · `backend/src/routes/borewellRoutes.js`
- [Controller](https://github.com/mehulsri07/stratadesk/blob/main/backend/src/controllers/borewellController.js): request logic · Handles API requests and business rules · `backend/src/controllers/borewellController.js`
- [DB pool](https://github.com/mehulsri07/stratadesk/blob/main/backend/src/db/pool.js): postgres client · Manages PostgreSQL connectivity and query pooling · `backend/src/db/pool.js`
- [DB init](https://github.com/mehulsri07/stratadesk/blob/main/backend/src/db/init.js): bootstrap · Initializes backend database setup and startup behavior · `backend/src/db/init.js`
- [PostgreSQL](https://github.com/mehulsri07/stratadesk/blob/main/database/init.sql): data store · Persistent storage for borewell and strata records · `database/init.sql`

### Deployment

Container and reverse-proxy boundary for production delivery

- [nginx](https://github.com/mehulsri07/stratadesk/blob/main/nginx/nginx.conf): reverse proxy · Serves the built client and forwards API traffic in production · `nginx/nginx.conf`
- [Compose](https://github.com/mehulsri07/stratadesk/blob/main/docker-compose.yml): orchestration · Starts database, API, and proxy/frontend services together · `docker-compose.yml`

## Connections

- Compose → nginx: runs · Orchestrates the production proxy/frontend container
- Compose → API app: runs · Starts the API service container
- Compose → PostgreSQL: starts · Brings up the database service for the stack
- nginx → App shell: serves · Delivers the built client application
- nginx → API app: proxies /api · Forwards API requests to the backend service
- App shell → Pages: renders · Mounts the main application pages
- App shell → Top bar: includes · Places global chrome in the app shell
- App shell → App state: provides · Shares state across the client surface
- Pages → Panels: composes · Uses workspace layout components
- Pages → Dashboard: shows · Hosts the dashboard-oriented screen pieces
- Pages → Map view: shows · Renders the geographic visualization surface
- Pages → Import flow: routes to · Provides the import workflow page
- Dashboard → Cross-section: uses · Connects dashboard views to geological cross-sections
- Cross-section → Engine: depends on · Delegates interpolation and geometry calculations
- Cross-section → Models: uses · Consumes shared domain models
- Charts → Models: uses · Shares the same borewell/strata contracts
- Map view → Models: uses · Reads the common domain model for map rendering
- API client → API app: calls · Sends client requests to the REST API
- API app → Borewell API: mounts · Registers borewell route handlers
- Borewell API → Controller: delegates · Passes request handling to controller logic
- Controller → DB pool: queries · Uses pooled PostgreSQL access for persistence
- DB init → PostgreSQL: initializes · Bootstraps the database schema and startup state
- DB pool → PostgreSQL: connects to · Reads and writes application data
