How ac4747/moon works
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: App.jsx Browser UI · main.py FastAPI API · Analyze.jsx Analyze · model_runner.py Inference Pipeline
Components 18
Frontend
React/Vite user interface and client-side visualization
- Browser UI · User-facing dashboard for upload, visualization, and results review
moon-frontend/src/App.jsx - Home · Landing and upload entry page
moon-frontend/src/pages/Home.jsx - Analyze · Interactive analysis workspace with moon view
moon-frontend/src/pages/Analyze.jsx - Dashboard · Results overview and status dashboard
moon-frontend/src/pages/Dashboard.jsx - App State · Shared upload, status, and results state
moon-frontend/src/context/AppContext.jsx - Upload Hook · Client-side upload and submit workflow
moon-frontend/src/hooks/useUpload.js - Results Hook · Fetches detections and result payloads
moon-frontend/src/hooks/useFetchResults.js - API Client · Central HTTP boundary to backend endpoints
moon-frontend/src/services/api.js - Detection API · Domain-specific detection and result requests
moon-frontend/src/services/detectionService.js - Upload Rail · Drag-and-drop and upload entry controls
moon-frontend/src/components/upload/UploadBox.jsx - Moon View · Client-side interactive moon scene with hazard markers
moon-frontend/public/models/moon.glb - Results Panel · Annotated imagery, overlays, stats, and info display
moon-frontend/src/components/results/ResultImage.jsx
Backend
FastAPI API, inference orchestration, and persisted artifacts
- FastAPI API · HTTP boundary for upload, detection, and retrieval
backend/main.py - Inference Pipeline · Runs remote segmentation, extracts regions, and generates artifacts
backend/model_runner.py - Artifacts · Uploads, outputs, and generated result files
backend/static
Runtime
External model service and deployment/runtime boundaries
- HF Space · Remote Gradio/Hugging Face segmentation dependency
- Frontend Deploy · Vercel/Netlify deployment boundary for the client app
moon-frontend/vercel.json - Backend Deploy · Railway/Procfile deployment boundary for the API
backend/railway.json
Connections 20
- 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