How mehulsri07/stratadesk works
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: MapDashboardPage.tsx Pages · main.tsx App shell · app.js API app · docker-compose.yml Compose
Components 21
Frontend
React/Vite client for visualization and import workflows
- App shell · Bootstraps the client and wires the shared page shell
src/main.tsx - Pages · Primary map/dashboard and borewell import screens
src/pages/MapDashboardPage.tsx - App state · Shared application state across panels and pages
src/store/AppContext.tsx - Panels · Workspace layout pieces such as sidebars, drawers, and panels
src/components/panels/LeftSidebar.tsx - Top bar · Global app header and navigation chrome
src/components/TopBar.tsx - Dashboard · Dashboard composition for borewell cards and section navigation
src/components/dashboard/DashboardHeader.tsx - Map view · Spatial strata visualization on the dashboard
src/components/map/StrataMap.tsx - Import flow · Borewell import surface for spreadsheet-driven data entry
src/pages/BorewellImportPage.tsx - Cross-section · Geological cross-section rendering and interpretation
src/components/CrossSection/CrossSectionView.tsx - Engine · Interpolation and geo utilities for cross-section calculations
src/lib/crossSectionEngine.ts - Charts · Chart-based strata and cross-section presentations
src/components/charts/StrataChart.tsx - Models · Shared borewell and strata contracts used across client features
src/types/models.ts - API client · Frontend request layer for backend interactions
src/lib/api.ts
Backend
Express API and PostgreSQL access layer
- API app · Configures middleware and mounts REST routes
backend/src/app.js - Borewell API · HTTP surface for borewell data operations
backend/src/routes/borewellRoutes.js - Controller · Handles API requests and business rules
backend/src/controllers/borewellController.js - DB pool · Manages PostgreSQL connectivity and query pooling
backend/src/db/pool.js - DB init · Initializes backend database setup and startup behavior
backend/src/db/init.js - PostgreSQL · Persistent storage for borewell and strata records
database/init.sql
Connections 23
- 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