# sterben-209/logistic architecture

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

- Interactive diagram: https://gitdiagram.com/sterben-209/logistic
- Repository: https://github.com/sterben-209/logistic

## Overview

1. **Repo shape**
   - This repository is not a single application; it contains **two mostly separate front-end/code-generation workspaces**:
     - `port_zoning_map/` — a React/Vite geospatial app.
     - `stitch_ai_yard_pathfinding_system/` — a static HTML/SPA assembly workspace with many generated UI variants and patch scripts.
   - The root `README.md` is effectively empty, so the directory structure is the best source of truth.

2. **`port_zoning_map` runtime**
   - This is a **browser SPA** built with **React + Vite**.
   - The runtime entrypoints are `src/main.jsx` and `src/App.jsx`, with styling in `src/App.css` and `src/index.css`.
   - The app centers on two UI components:
     - `PortZoningMap.jsx` for map/zoning visualization.
     - `FreePortDigitizer.jsx` for digitizing or editing port-related geometry.

3. **`port_zoning_map` service boundary**
   - Business logic is pushed into `src/services/`, which acts as the integration boundary:
     - `mapService.js` for map-related interactions.
     - `osmService.js` for OpenStreetMap data access.
     - `routingService.js` for route/path calculations.
     - `supabaseService.js` for backend persistence/auth/data access.
     - `turfService.js` for geospatial operations using Turf-style geometry helpers.
   - This separation suggests a flow of **UI → service layer → external APIs/data store → UI update**.

4. **`port_zoning_map` external dependencies**
   - The main external systems implied by the file tree are:
     - **OpenStreetMap** for basemap or geographic data.
     - **Supabase** as the backend/database boundary.
     - **Geospatial libraries** for computation and shape manipulation.
   - `supabase_schema.sql` defines the database contract, and `test_supabase.js` / `test_route.js` indicate validation against those integrations.

5. **`port_zoning_map` data assets**
   - `public/dummy_*.json` files provide local sample data for development/demo flows.
   - These dummy datasets likely stand in for vehicle, traffic, and CHE/container-handling equipment inputs.
   - `src/oldViews.js` and `extract_views.py` suggest a migration or refactor path from older UI views into the current component structure.

6. **`port_zoning_map` architectural intent**
   - The app appears focused on **port zoning and spatial digitization** rather than generic CRUD.
   - The core architectural boundary is between:
     - **interactive map editing / visualization in the browser**, and
     - **persisted geospatial state in Supabase plus route/OSM services**.

7. **`stitch_ai_yard_pathfinding_system` runtime style**
   - This workspace is more of a **static SPA generator / UI assembly toolkit** than a conventional app server.
   - It contains `index.html`, `map_digitizer.html`, `dev_server.py`, and `build_spa.py`, suggesting a locally served static site that can be rebuilt or patched.
   - The primary output artifacts are the many `nexus_terminal_*` directories, each containing a `code.html` snapshot.

8. **`stitch_ai_yard_pathfinding_system` generation pipeline**
   - The Python scripts (`inject_*.py`, `rewrite_*.py`, `merge_login.py`, `fix_*.py`) indicate a workflow of **programmatic HTML/UI modification**.
   - These scripts likely:
     - inject CRUD/editing logic,
     - add Supabase wiring,
     - normalize layout/styling,
     - and merge or repair feature-specific pages.
   - This is a build-time transformation boundary, not a runtime service boundary.

9. **`stitch_ai_yard_pathfinding_system` feature slices**
   - The `nexus_terminal_*` folders represent **distinct product views or modules**:
     - admin login / request access,
     - analytics,
     - container management,
     - inventory,
     - logistics,
     - operations command,
     - map digitizer,
     - and a 3D stacking heatmap yard UI.
   - Architecturally, these look like **page-level variants** sharing a common design system and data model rather than separately deployed apps.

10. **Shared backend theme**
   - Both subprojects point toward **Supabase-backed data persistence** and browser-side geospatial/ops tooling.
   - There is no obvious custom server-side API in the repository; instead, the architecture is mostly:
     - **client/UI layer**,
     - **lightweight script/build layer**,
     - **Supabase and other external services**.

11. **What to draw as the main boundaries**
   - For an architecture diagram, the key boxes are:
     - **React/Vite port zoning SPA** with service adapters to OSM, routing, Turf, and Supabase.
     - **Static UI generation workspace** that produces multiple terminal-style pages from editable HTML templates.
     - **Supabase database** as the persistence boundary.
     - **External geospatial/routing sources** as read-side dependencies.

12. **Overall interpretation**
   - This repo looks like a **logistics/port operations product family** with one focused interactive geospatial app and one broader yard/terminal UI prototyping system.
   - The main architectural theme is **browser-based operational tooling with geospatial logic and Supabase-backed state**, supported by a set of scripts for generating and patching UI variants.

Main entry points: [`port_zoning_map/src/services`](https://github.com/sterben-209/logistic/tree/main/port_zoning_map/src/services) (Service layer), [`stitch_ai_yard_pathfinding_system/nexus_terminal`](https://github.com/sterben-209/logistic/tree/main/stitch_ai_yard_pathfinding_system/nexus_terminal) (Terminal views), [`port_zoning_map/src/App.jsx`](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/App.jsx) (Port Zoning SPA), [`port_zoning_map/src/components/PortZoningMap.jsx`](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/components/PortZoningMap.jsx) (Port map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_port["port_zoning_map"]
  node_node_port_app["Port Zoning SPA<br/>React/Vite app<br/>[App.jsx]"]
  node_node_port_entry["App entry<br/>SPA bootstrap<br/>[main.jsx]"]
  node_node_port_map["Port map<br/>map UI<br/>[PortZoningMap.jsx]"]
  node_node_port_digitizer["Digitizer<br/>editing UI"]
  node_node_port_services{{"Service layer<br/>integration boundary"}}
  node_node_port_osm["OSM service<br/>data adapter<br/>[osmService.js]"]
  node_node_port_route["Routing service<br/>route engine<br/>[routingService.js]"]
  node_node_port_supabase["Supabase service<br/>backend adapter<br/>[supabaseService.js]"]
  node_node_port_turf["Turf service<br/>geo ops<br/>[turfService.js]"]
  node_node_port_data[("Sample data<br/>demo assets")]
end

subgraph group_group_stitch["stitch_ai_yard_pathfinding_system"]
  node_node_stitch_spa["UI assembly<br/>static SPA workspace<br/>[index.html]"]
  node_node_stitch_dev["Dev server<br/>local runner<br/>[dev_server.py]"]
  node_node_stitch_build["Build script<br/>generator<br/>[build_spa.py]"]
  node_node_stitch_patches["Patch scripts<br/>transform pipeline<br/>[inject_supabase.py]"]
  node_node_stitch_views["Terminal views<br/>generated pages"]
  node_node_stitch_mapdigit["Map digitizer<br/>generated view<br/>[map_digitizer.html]"]
  node_node_stitch_ops["Operations UI<br/>generated view<br/>[code.html]"]
  node_node_stitch_supabase["Supabase wiring<br/>backend adapter<br/>[inject_supabase.py]"]
end

subgraph group_group_external["external systems"]
  node_node_port_schema["DB schema<br/>SQL contract"]
  node_node_external_supabase[("Supabase<br/>database/backend")]
  node_node_external_osm[("OpenStreetMap<br/>map data source")]
  node_node_external_geo(("Geospatial libs<br/>spatial computation"))
end

node_node_port_entry -->|"boots"| node_node_port_app
node_node_port_app -->|"renders"| node_node_port_map
node_node_port_app -->|"renders"| node_node_port_digitizer
node_node_port_map -->|"uses"| node_node_port_services
node_node_port_digitizer -->|"uses"| node_node_port_services
node_node_port_services -->|"reads"| node_node_port_osm
node_node_port_services -->|"calculates"| node_node_port_route
node_node_port_services -->|"processes"| node_node_port_turf
node_node_port_services -->|"persists"| node_node_port_supabase
node_node_port_supabase -->|"connects"| node_node_external_supabase
node_node_port_osm -->|"connects"| node_node_external_osm
node_node_port_turf -->|"uses"| node_node_external_geo
node_node_port_schema -.->|"defines"| node_node_external_supabase
node_node_port_data -.->|"seeds"| node_node_port_map
node_node_stitch_dev -->|"serves"| node_node_stitch_spa
node_node_stitch_build -->|"builds"| node_node_stitch_views
node_node_stitch_patches -->|"modifies"| node_node_stitch_views
node_node_stitch_spa -->|"contains"| node_node_stitch_views
node_node_stitch_mapdigit -.->|"belongs to"| node_node_stitch_views
node_node_stitch_ops -.->|"belongs to"| node_node_stitch_views
node_node_stitch_supabase -->|"connects"| node_node_external_supabase
node_node_stitch_views -->|"wires"| node_node_stitch_supabase

click node_node_port_app "https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/App.jsx"
click node_node_port_entry "https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/main.jsx"
click node_node_port_map "https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/components/PortZoningMap.jsx"
click node_node_port_digitizer "https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/components/FreePortDigitizer.jsx"
click node_node_port_services "https://github.com/sterben-209/logistic/tree/main/port_zoning_map/src/services"
click node_node_port_osm "https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/services/osmService.js"
click node_node_port_route "https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/services/routingService.js"
click node_node_port_supabase "https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/services/supabaseService.js"
click node_node_port_turf "https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/services/turfService.js"
click node_node_port_data "https://github.com/sterben-209/logistic/blob/main/port_zoning_map/public/dummy_vehicles.json"
click node_node_port_schema "https://github.com/sterben-209/logistic/blob/main/port_zoning_map/supabase_schema.sql"
click node_node_stitch_spa "https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/index.html"
click node_node_stitch_dev "https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/dev_server.py"
click node_node_stitch_build "https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/build_spa.py"
click node_node_stitch_patches "https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/inject_supabase.py"
click node_node_stitch_views "https://github.com/sterben-209/logistic/tree/main/stitch_ai_yard_pathfinding_system/nexus_terminal"
click node_node_stitch_mapdigit "https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/map_digitizer.html"
click node_node_stitch_ops "https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/nexus_terminal_operations_command/code.html"
click node_node_stitch_supabase "https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/inject_supabase.py"

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_node_port_app,node_node_port_entry,node_node_port_map,node_node_port_digitizer,node_node_port_services,node_node_port_osm,node_node_port_route,node_node_port_supabase,node_node_port_turf,node_node_port_data toneBlue
class node_node_stitch_spa,node_node_stitch_dev,node_node_stitch_build,node_node_stitch_patches,node_node_stitch_views,node_node_stitch_mapdigit,node_node_stitch_ops,node_node_stitch_supabase toneAmber
class node_node_port_schema,node_node_external_supabase,node_node_external_osm,node_node_external_geo toneMint
```

## Components

### port_zoning_map

React/Vite geospatial SPA for port zoning and digitization

- [Port Zoning SPA](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/App.jsx): React/Vite app · Browser app for port zoning, map visualization, and geometry editing · `port_zoning_map/src/App.jsx`
- [App entry](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/main.jsx): SPA bootstrap · Main browser entrypoint and app initialization · `port_zoning_map/src/main.jsx`
- [Port map](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/components/PortZoningMap.jsx): map UI · Primary zoning visualization and interaction surface · `port_zoning_map/src/components/PortZoningMap.jsx`
- [Digitizer](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/components/FreePortDigitizer.jsx): editing UI · Geometry capture and port feature editing component · `port_zoning_map/src/components/FreePortDigitizer.jsx`
- [Service layer](https://github.com/sterben-209/logistic/tree/main/port_zoning_map/src/services): integration boundary · Client-side adapters for mapping, routing, geospatial logic, and persistence · `port_zoning_map/src/services`
- [OSM service](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/services/osmService.js): data adapter · OpenStreetMap access and geographic data lookup · `port_zoning_map/src/services/osmService.js`
- [Routing service](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/services/routingService.js): route engine · Route and path calculation logic · `port_zoning_map/src/services/routingService.js`
- [Supabase service](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/services/supabaseService.js): backend adapter · Authentication, persistence, and data access bridge · `port_zoning_map/src/services/supabaseService.js`
- [Turf service](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/src/services/turfService.js): geo ops · Geospatial helpers for geometry and spatial operations · `port_zoning_map/src/services/turfService.js`
- [Sample data](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/public/dummy_vehicles.json): demo assets · Local JSON fixtures for vehicles, traffic, and CHE inputs · `port_zoning_map/public/dummy_vehicles.json`

### stitch_ai_yard_pathfinding_system

Static SPA assembly workspace with generated terminal views and patch scripts

- [UI assembly](https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/index.html): static SPA workspace · Static HTML workspace for assembling and serving generated terminal pages · `stitch_ai_yard_pathfinding_system/index.html`
- [Dev server](https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/dev_server.py): local runner · Local static server for previewing the generated SPA · `stitch_ai_yard_pathfinding_system/dev_server.py`
- [Build script](https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/build_spa.py): generator · Rebuilds or assembles SPA artifacts from templates and patches · `stitch_ai_yard_pathfinding_system/build_spa.py`
- [Patch scripts](https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/inject_supabase.py): transform pipeline · Injected and rewrite scripts for CRUD, login, editing, layout, and Supabase wiring · `stitch_ai_yard_pathfinding_system/inject_supabase.py`
- [Terminal views](https://github.com/sterben-209/logistic/tree/main/stitch_ai_yard_pathfinding_system/nexus_terminal): generated pages · Collection of page-level UI variants for operations, analytics, inventory, logistics, and digitizer flows · `stitch_ai_yard_pathfinding_system/nexus_terminal`
- [Map digitizer](https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/map_digitizer.html): generated view · Standalone digitizer page variant in the terminal UI family · `stitch_ai_yard_pathfinding_system/map_digitizer.html`
- [Operations UI](https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/nexus_terminal_operations_command/code.html): generated view · Operations command and spatial yard views among the generated terminal pages · `stitch_ai_yard_pathfinding_system/nexus_terminal_operations_command/code.html`
- [Supabase wiring](https://github.com/sterben-209/logistic/blob/main/stitch_ai_yard_pathfinding_system/inject_supabase.py): backend adapter · Generated frontend integration for Supabase-backed workflows · `stitch_ai_yard_pathfinding_system/inject_supabase.py`

### external systems

Databases and third-party geospatial/routing dependencies

- [DB schema](https://github.com/sterben-209/logistic/blob/main/port_zoning_map/supabase_schema.sql): SQL contract · Supabase schema and database shape for the port app · `port_zoning_map/supabase_schema.sql`
- **Supabase**: database/backend · Shared persistence and authentication boundary
- **OpenStreetMap**: map data source · External geographic basemap and data source
- **Geospatial libs**: spatial computation · External geometry and turf-style spatial processing libraries

## Connections

- App entry → Port Zoning SPA: boots · Browser entry initializes the React app
- Port Zoning SPA → Port map: renders · Primary app surface is the zoning map
- Port Zoning SPA → Digitizer: renders · App also exposes digitizing/editing workflows
- Port map → Service layer: uses · Map UI delegates data and spatial work to services
- Digitizer → Service layer: uses · Digitizer relies on integration services for geometry and persistence
- Service layer → OSM service: reads · Service layer fetches map/geographic data
- Service layer → Routing service: calculates · Service layer computes routes and paths
- Service layer → Turf service: processes · Service layer performs geospatial operations
- Service layer → Supabase service: persists · Service layer stores and retrieves app state
- Supabase service → Supabase: connects · Supabase service is the backend boundary
- OSM service → OpenStreetMap: connects · OSM adapter reads external geographic data
- Turf service → Geospatial libs: uses · Geospatial helpers depend on spatial computation libraries
- DB schema → Supabase: defines · SQL schema defines the persistence contract
- Sample data → Port map: seeds · Local JSON fixtures support development and demos
- Dev server → UI assembly: serves · Local server previews the static workspace
- Build script → Terminal views: builds · Build step produces the page variants
- Patch scripts → Terminal views: modifies · Patch scripts rewrite and enrich generated UI pages
- UI assembly → Terminal views: contains · Workspace centers on many generated terminal views
- Map digitizer → Terminal views: belongs to · Digitizer page is one of the generated view variants
- Operations UI → Terminal views: belongs to · Operations command page is one generated variant
- Supabase wiring → Supabase: connects · Generated pages use Supabase for persistence flows
- Terminal views → Supabase wiring: wires · Terminal views are patched with backend integration
