Repository map

In simple terms

This page is the map of the codebase: what each folder is for, so you can find the right place to look or change something. Read it once and you’ll know where to go for the UI, the physics engines, the API, or the data.

Top level

Path	What it is
backend/	Python: the calculation engines, the web API, and storage.
frontend/	The browser app (Vite + React + TypeScript).
docs/	This documentation (renders on GitHub and in-app at /docs).
README.md	The user-facing introduction and set-up steps.
Dockerfile · .dockerignore	The app’s image: the page built inside it, the locked Python packages, the code and the data the app ships (Run with Docker).
docker/	The image’s entrypoint and health check; the server recipe (docker-compose.yml with Caddy, Caddyfile) and its README.md.
scripts/build_image.sh	Builds the image from the committed code only (git archive of HEAD).
docker/image.workflow.yml	The image workflow, kept beside the recipe until it is enabled under .github/workflows/: builds both platforms, smoke-tests, pushes — on a release tag or by hand.
requirements.txt	Python dependencies (pinned FastAPI 0.95 / Pydantic v1 line).
.env	Local config: data paths, solver choice, host/port. No secrets.

backend/ — engines, API, storage

backend/
  api/
    app.py            FastAPI app — the HTTP routes; the web layer (thin).
    controllers.py    PtxApi — framework-agnostic orchestration ("do the thing").
  core/               The domain logic. Nothing here imports FastAPI.
    engine/           ProjectConfig (S1–S9 config sections) + topology (build/validate).
    components/        wind, solar, bess, electrolyser, desalination, asu +
       derivatives/    ammonia, methanol, methanation, dri, eaf, saf, …
    financials/       capex · opex · indicators (NH3) · multi (per-product LCO).
    parameters/       book.py (book→typed params) · technical · financial · references.
    timeseries/       load/clean/resample weather; solver_frame (the 8760h frame).
    documents/        the Excel/HTML/zip document standard (import + export).
    projects/         service.py (create) · workspace.py (book + snapshots orchestration).
    prefeasibility.py  closed-form NH3 + right-size helpers.
    run.py            run_prefeasibility_auto, run_greedy_from_config, right-size + landscape.
    greedy.py         the Mode-B hourly simulation (8760h, no foresight).
    feasibility.py    the PyPSA + HiGHS hourly LP (the bankable dispatch).
    dispatch_store.py  persists a feasibility solve (Parquet frame + JSON sidecar).
    solve_queue.py    the solve queue: at most PTX_SOLVE_WORKERS engine jobs run at
                      once, the rest wait their turn (reported "queued").
    contracts.py      SolveResult / PostProcessResult (typed twins of the API shapes).
  db/                 repository.py (interface) + SQLite stores: projects, assumptions,
                      snapshots, dab_versions (each workspace's default books + the
                      shipped ones), book_versions, sites, identity, throttle (the
                      sign-in failures).
  data/               dab/ (the default books shipped with the app) · dab_workspaces/
                      (each workspace's own) · raw|processed|results/<project_id>/ ·
                      exports/   (all but dab/ gitignored).
  tests/              the pytest suite.

Counted from the code: app.py declares 163 routes; backend/tests/ holds 95 test files with

1,065 test functions.

Rule of thumb: new physics/economics → core/; new orchestration → controllers.py; new HTTP surface → app.py. core/ never imports the web framework, so engines stay testable in isolation.

frontend/src/ — the browser app

frontend/src/
  main.tsx            Entry: mounts <App/> inside <BrowserRouter>.
  App.tsx             The route table (portfolio → project → rooms; /docs).
  layouts/
    AppLayout.tsx     Global chrome: brand, breadcrumb, theme toggle, settings.
    ProjectLayout.tsx Per-project chrome: version bars, stage/room sidebar.
  pages/              PortfolioLanding · NewProjectForm · SettingsDab ·
                      DocsRoute · PlaceholderRoom.
  rooms/              One folder per stage/tool:
    prefeasibility/    the cockpit + methods + landscape + right-size control.
    feasibility/       dispatch · inputs · methods · reliability · storage lab.
    assumptions/  snapshots/  derivatives/
  components/         Shared UI: FlowDiagram, charts (Cost/Energy/Capex/Lco/…),
                      Panel, RoomHeader, MetricCard, ThemeToggle, docs/*.
  data/
    client.ts         Intent-revealing wrappers the UI calls.
    api.ts            Typed fetch against VITE_API_BASE (default :8000).
    types.ts          Shared TS shapes mirroring the backend.
    docs.ts           Loads the docs/ Markdown tree (build-time glob).
  index.css           Design tokens (colors, spacing, type) — light + dark.
  App.css             Component styles.
  format.ts           Locale-safe number/date formatting.

Rule of thumb: the UI depends only on client.ts; client.ts → api.ts → FastAPI is the data seam. Never let a component fetch directly or invent a field the backend doesn’t return.

Where to start for common tasks

I want to…	Start in…
Change how a screen looks/behaves	the matching rooms/… folder
Add/change an API field	core/ producer → api.ts type → client.ts/room
Change the physics/economics	backend/core/… + its test in backend/tests/
Add a component to the value chain	core/components/… + topology.py
Change a default assumption	the DAB (backend/data/dab/) / Settings room

Related topics

• System architecture
• Application overview