# ac4747/moon architecture

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

- Interactive diagram: https://gitdiagram.com/ac4747/moon
- Repository: https://github.com/ac4747/moon

## Overview

1. **Top-level shape**
   - Lunar Forge is a two-tier app: a **React/Vite frontend** in `moon-frontend/` and a **FastAPI backend** in `backend/`.
   - The frontend is the user-facing analysis dashboard; the backend owns file handling, inference orchestration, and result generation.
   - The deployment boundary is explicitly split: frontend for static hosting, backend for API hosting.

2. **Frontend responsibility**
   - The frontend is organized around three user areas: **upload**, **interactive moon view**, and **results dashboard**.
   - Pages live in `src/pages/` (`Home`, `Analyze`, `Dashboard`) and the shared layout/UI lives under `src/components/ui/`.
   - Result rendering is separated into `src/components/results/`, which suggests the UI treats inference output as a distinct subsystem.

3. **Frontend state and API flow**
   - `src/context/AppContext.jsx` acts as the shared state boundary for app-wide data such as upload state, analysis results, and status.
   - Custom hooks in `src/hooks/` (`useUpload`, `useFetchResults`) isolate network actions from components.
   - API access is centralized in `src/services/api.js` and `src/services/detectionService.js`, which keeps the UI decoupled from backend URL details.

4. **3D visualization subsystem**
   - The center visualization uses **Three.js / @react-three/fiber / @react-three/drei**, backed by the 3D asset `public/models/moon.glb`.
   - This is not just decorative: the README says hazard markers are mapped onto an interactive moon view.
   - The 3D globe is a client-side rendering concern, while the terrain preview returned by the backend is a separate generated image.

5. **Upload entry point**
   - The left-side upload rail (`UploadRail`, `UploadBox`, `DragDrop`) is the user’s entry into the pipeline.
   - The frontend sends the selected image to the backend over HTTP, either to a file-only upload endpoint or the full analysis endpoint.
   - This is the main transition from browser state to server-side processing.

6. **Backend API layer**
   - `backend/main.py` is the FastAPI application and route boundary.
   - The API includes health and stats endpoints plus upload/detection endpoints:
     - `GET /healthz`
     - `GET /stats`
     - `POST /upload`
     - `POST /detect`
     - `GET /detections/{upload_id}`
   - `GET /docs` exposes the FastAPI/OpenAPI contract for inspection.

7. **Inference and image-processing pipeline**
   - The heavy lifting is in `backend/model_runner.py`.
   - The pipeline reads the uploaded image, calls the remote segmentation model, converts masks into contours/boxes, annotates the image, and generates a terrain-style preview.
   - Output from this layer is structured for the UI: detection counts, region metadata, model status, and URLs to generated artifacts.

8. **External model dependency**
   - Inference depends on a **public Hugging Face Space** (`prithivMLmods/SAM3-Demo`) rather than a local model server.
   - The backend calls it through `gradio_client.Client(...).predict(...)` twice, once for `boulder` and once for `crater`.
   - This is a major architecture boundary: model availability and latency are externalized, so the app must surface remote-service status to users.

9. **Persistence and generated artifacts**
   - The backend stores runtime uploads and generated outputs on disk, with directories like `uploads/` and `outputs/`.
   - README and env examples show a persistence strategy based on `/data` mounts, with **Postgres preferred** and **SQLite fallback**.
   - This means the backend is responsible not only for inference but also for serving previously generated results by upload ID.

10. **Failure handling and user-visible status**
   - The app is designed to distinguish between “no detections” and “model unavailable.”
   - Retries, raw Hugging Face messages, and model-health fields are returned to the frontend and displayed in the results panel.
   - That makes remote inference failures part of the product UX, not just a backend log concern.

11. **Deployment and runtime boundaries**
   - Backend runtime is Python/FastAPI/Uvicorn; frontend runtime is Node/Vite.
   - `backend/railway.json`, `backend/Procfile`, `moon-frontend/vercel.json`, and `moon-frontend/netlify.toml` show cloud deployment wiring.
   - CORS and environment variables connect the two tiers: the frontend points to the backend via `VITE_API_URL`, and the backend allows the frontend origin.

12. **What an architecture diagram should emphasize**
   - Show a **browser UI** feeding images into a **FastAPI API**.
   - From the API, draw a branch to **persistent storage** for uploads/results and another branch to the **external Hugging Face inference service**.
   - Then show the returned artifacts flowing back to the frontend as:
     - counts and region metadata
     - annotated image
     - 3D terrain preview
     - model status / raw service messages
   - Keep the interactive 3D moon view as a client-side visualization subsystem separate from backend-generated imagery.

Main entry points: [`moon-frontend/src/App.jsx`](https://github.com/ac4747/moon/blob/main/moon-frontend/src/App.jsx) (Browser UI), [`backend/main.py`](https://github.com/ac4747/moon/blob/main/backend/main.py) (FastAPI API), [`moon-frontend/src/pages/Analyze.jsx`](https://github.com/ac4747/moon/blob/main/moon-frontend/src/pages/Analyze.jsx) (Analyze), [`backend/model_runner.py`](https://github.com/ac4747/moon/blob/main/backend/model_runner.py) (Inference Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser_app["Browser UI<br/>React/Vite app<br/>[App.jsx]"]
  node_home_page["Home<br/>page<br/>[Home.jsx]"]
  node_analyze_page["Analyze<br/>page<br/>[Analyze.jsx]"]
  node_dashboard_page["Dashboard<br/>page<br/>[Dashboard.jsx]"]
  node_app_context(("App State<br/>context<br/>[AppContext.jsx]"))
  node_upload_hook["Upload Hook<br/>[useUpload.js]"]
  node_results_hook["Results Hook<br/>[useFetchResults.js]"]
  node_api_client["API Client<br/>[api.js]"]
  node_detection_service["Detection API"]
  node_upload_ui["Upload Rail<br/>[UploadBox.jsx]"]
  node_moon_view{{"Moon View<br/>3d visualization<br/>[moon.glb]"}}
  node_results_ui["Results Panel<br/>component set<br/>[ResultImage.jsx]"]
end

subgraph group_backend["Backend"]
  node_api_server["FastAPI API<br/>web api<br/>[main.py]"]
  node_inference_pipeline["Inference Pipeline<br/>processor<br/>[model_runner.py]"]
  node_artifact_store[("Artifacts<br/>disk storage")]
end

subgraph group_runtime["Runtime"]
  node_model_service{{"HF Space<br/>external model"}}
  node_deployment_frontend["Frontend Deploy<br/>static hosting<br/>[vercel.json]"]
  node_deployment_backend["Backend Deploy<br/>python runtime<br/>[railway.json]"]
end

node_browser_app -->|"renders"| node_home_page
node_browser_app -->|"renders"| node_analyze_page
node_browser_app -->|"renders"| node_dashboard_page
node_home_page -->|"uses"| node_upload_ui
node_upload_ui -->|"submits"| node_upload_hook
node_analyze_page -->|"visualizes"| node_moon_view
node_analyze_page -->|"shows"| node_results_ui
node_dashboard_page -->|"summarizes"| node_results_ui
node_browser_app -->|"shares state"| node_app_context
node_upload_hook -->|"calls"| node_api_client
node_results_hook -->|"fetches"| node_detection_service
node_detection_service -->|"uses"| node_api_client
node_api_client -->|"requests"| node_api_server
node_api_server -->|"orchestrates"| node_inference_pipeline
node_inference_pipeline -->|"predicts"| node_model_service
node_inference_pipeline -->|"writes"| node_artifact_store
node_api_server -->|"serves"| node_artifact_store
node_api_server -->|"returns results"| node_browser_app
node_deployment_frontend -.->|"hosts"| node_browser_app
node_deployment_backend -.->|"runs"| node_api_server

click node_browser_app "https://github.com/ac4747/moon/blob/main/moon-frontend/src/App.jsx"
click node_home_page "https://github.com/ac4747/moon/blob/main/moon-frontend/src/pages/Home.jsx"
click node_analyze_page "https://github.com/ac4747/moon/blob/main/moon-frontend/src/pages/Analyze.jsx"
click node_dashboard_page "https://github.com/ac4747/moon/blob/main/moon-frontend/src/pages/Dashboard.jsx"
click node_app_context "https://github.com/ac4747/moon/blob/main/moon-frontend/src/context/AppContext.jsx"
click node_upload_hook "https://github.com/ac4747/moon/blob/main/moon-frontend/src/hooks/useUpload.js"
click node_results_hook "https://github.com/ac4747/moon/blob/main/moon-frontend/src/hooks/useFetchResults.js"
click node_api_client "https://github.com/ac4747/moon/blob/main/moon-frontend/src/services/api.js"
click node_detection_service "https://github.com/ac4747/moon/blob/main/moon-frontend/src/services/detectionService.js"
click node_upload_ui "https://github.com/ac4747/moon/blob/main/moon-frontend/src/components/upload/UploadBox.jsx"
click node_moon_view "https://github.com/ac4747/moon/blob/main/moon-frontend/public/models/moon.glb"
click node_results_ui "https://github.com/ac4747/moon/blob/main/moon-frontend/src/components/results/ResultImage.jsx"
click node_api_server "https://github.com/ac4747/moon/blob/main/backend/main.py"
click node_inference_pipeline "https://github.com/ac4747/moon/blob/main/backend/model_runner.py"
click node_artifact_store "https://github.com/ac4747/moon/tree/main/backend/static"
click node_deployment_frontend "https://github.com/ac4747/moon/blob/main/moon-frontend/vercel.json"
click node_deployment_backend "https://github.com/ac4747/moon/blob/main/backend/railway.json"

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_browser_app,node_home_page,node_analyze_page,node_dashboard_page,node_app_context,node_upload_hook,node_results_hook,node_api_client,node_detection_service,node_upload_ui,node_moon_view,node_results_ui toneBlue
class node_api_server,node_inference_pipeline,node_artifact_store toneAmber
class node_model_service,node_deployment_frontend,node_deployment_backend toneMint
```

## Components

### Frontend

React/Vite user interface and client-side visualization

- [Browser UI](https://github.com/ac4747/moon/blob/main/moon-frontend/src/App.jsx): React/Vite app · User-facing dashboard for upload, visualization, and results review · `moon-frontend/src/App.jsx`
- [Home](https://github.com/ac4747/moon/blob/main/moon-frontend/src/pages/Home.jsx): page · Landing and upload entry page · `moon-frontend/src/pages/Home.jsx`
- [Analyze](https://github.com/ac4747/moon/blob/main/moon-frontend/src/pages/Analyze.jsx): page · Interactive analysis workspace with moon view · `moon-frontend/src/pages/Analyze.jsx`
- [Dashboard](https://github.com/ac4747/moon/blob/main/moon-frontend/src/pages/Dashboard.jsx): page · Results overview and status dashboard · `moon-frontend/src/pages/Dashboard.jsx`
- [App State](https://github.com/ac4747/moon/blob/main/moon-frontend/src/context/AppContext.jsx): context · Shared upload, status, and results state · `moon-frontend/src/context/AppContext.jsx`
- [Upload Hook](https://github.com/ac4747/moon/blob/main/moon-frontend/src/hooks/useUpload.js): hook · Client-side upload and submit workflow · `moon-frontend/src/hooks/useUpload.js`
- [Results Hook](https://github.com/ac4747/moon/blob/main/moon-frontend/src/hooks/useFetchResults.js): hook · Fetches detections and result payloads · `moon-frontend/src/hooks/useFetchResults.js`
- [API Client](https://github.com/ac4747/moon/blob/main/moon-frontend/src/services/api.js): service · Central HTTP boundary to backend endpoints · `moon-frontend/src/services/api.js`
- [Detection API](https://github.com/ac4747/moon/blob/main/moon-frontend/src/services/detectionService.js): service · Domain-specific detection and result requests · `moon-frontend/src/services/detectionService.js`
- [Upload Rail](https://github.com/ac4747/moon/blob/main/moon-frontend/src/components/upload/UploadBox.jsx): Drag-and-drop and upload entry controls · `moon-frontend/src/components/upload/UploadBox.jsx`
- [Moon View](https://github.com/ac4747/moon/blob/main/moon-frontend/public/models/moon.glb): 3d visualization · Client-side interactive moon scene with hazard markers · `moon-frontend/public/models/moon.glb`
- [Results Panel](https://github.com/ac4747/moon/blob/main/moon-frontend/src/components/results/ResultImage.jsx): component set · Annotated imagery, overlays, stats, and info display · `moon-frontend/src/components/results/ResultImage.jsx`

### Backend

FastAPI API, inference orchestration, and persisted artifacts

- [FastAPI API](https://github.com/ac4747/moon/blob/main/backend/main.py): web api · HTTP boundary for upload, detection, and retrieval · `backend/main.py`
- [Inference Pipeline](https://github.com/ac4747/moon/blob/main/backend/model_runner.py): processor · Runs remote segmentation, extracts regions, and generates artifacts · `backend/model_runner.py`
- [Artifacts](https://github.com/ac4747/moon/tree/main/backend/static): disk storage · Uploads, outputs, and generated result files · `backend/static`

### Runtime

External model service and deployment/runtime boundaries

- **HF Space**: external model · Remote Gradio/Hugging Face segmentation dependency
- [Frontend Deploy](https://github.com/ac4747/moon/blob/main/moon-frontend/vercel.json): static hosting · Vercel/Netlify deployment boundary for the client app · `moon-frontend/vercel.json`
- [Backend Deploy](https://github.com/ac4747/moon/blob/main/backend/railway.json): python runtime · Railway/Procfile deployment boundary for the API · `backend/railway.json`

## Connections

- Browser UI → Home: renders · Routes users into the landing and upload flow
- Browser UI → Analyze: renders · Hosts the interactive analysis workspace
- Browser UI → Dashboard: renders · Shows the results dashboard
- Home → Upload Rail: uses · Entry point for uploading images
- Upload Rail → Upload Hook: submits · Triggers upload actions from the browser
- Analyze → Moon View: visualizes · Displays the interactive lunar scene
- Analyze → Results Panel: shows · Presents detected regions and generated imagery
- Dashboard → Results Panel: summarizes · Surfaces counts, statuses, and result cards
- Browser UI → App State: shares state · Coordinates upload and result state across pages
- Upload Hook → API Client: calls · Sends file data to backend endpoints
- Results Hook → Detection API: fetches · Loads detection results by upload id
- Detection API → API Client: uses · Delegates transport to the shared HTTP client
- API Client → FastAPI API: requests · Frontend-to-backend API traffic
- FastAPI API → Inference Pipeline: orchestrates · Hands uploads to processing and result generation
- Inference Pipeline → HF Space: predicts · Calls the remote segmentation model for boulder and crater passes
- Inference Pipeline → Artifacts: writes · Persists uploads and generated outputs
- FastAPI API → Artifacts: serves · Returns previously generated results by upload id
- FastAPI API → Browser UI: returns results · Sends counts, metadata, images, and model status back to the UI
- Frontend Deploy → Browser UI: hosts · Static client deployment boundary
- Backend Deploy → FastAPI API: runs · Backend runtime and process boundary
