# r3nesh/root architecture

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

- Interactive diagram: https://gitdiagram.com/r3nesh/root
- Repository: https://github.com/r3nesh/root

## Overview

plot-to-plan turns plot dimensions, orientation and room requirements into a buildable house plan, then presents it as an editable 3D design. The main workflow runs from frontend inputs through the solve client and FastAPI to the CP-SAT solver, then uses the returned layout for visualization and walkthrough. The product also supports AI-assisted text and image inputs, local project recovery, design customization and cost/export tools. Some implementation excerpts are partial, so links between solver internals and unsampled feature modules are limited to documented or evident calls.

Main entry points: [`frontend/app/page.tsx`](https://github.com/r3nesh/root/blob/main/frontend/app/page.tsx) (Design workspace), [`backend/api/main.py`](https://github.com/r3nesh/root/blob/main/backend/api/main.py) (FastAPI endpoints), [`frontend/components/Scene.tsx`](https://github.com/r3nesh/root/blob/main/frontend/components/Scene.tsx) (3D scene), [`backend/solver/model.py`](https://github.com/r3nesh/root/blob/main/backend/solver/model.py) (CP-SAT layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Design interface"]
  node_page["Design workspace<br/>[page.tsx]"]
  node_studio["Design controls"]
  node_solvehook["Solve state<br/>[useSolve.ts]"]
end

subgraph group_planning["Plan generation"]
  node_solveclient["Solve client<br/>[solve.ts]"]
  node_ai_prompt_client["Prompt planning<br/>[aiPlan.ts]"]
  node_ai_image_client["Plan image input<br/>[aiPlanImage.ts]"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_promptplan["Prompt resolver<br/>[prompt_to_plan.py]"]
  node_ai_plan["AI plan parsing<br/>[plan_from_image.py]"]
  node_ai_facade["Facade analysis"]
  node_solver["CP-SAT layout<br/>[model.py]"]
  node_connectivity["Room connectivity<br/>[connectivity.py]"]
  node_realism["Plan realism<br/>[realism.py]"]
  node_zoning["Zoning rules<br/>[zoning.py]"]
  node_quantities["Plan quantities<br/>[quantities.py]"]
end

subgraph group_visualization["3D design"]
  node_scene["3D scene<br/>[Scene.tsx]"]
  node_walkthrough["Walkthrough controls<br/>[walkthrough.ts]"]
  node_materials["Materials and models"]
  node_furniture["Procedural furniture"]
end

subgraph group_outputs["Project outputs"]
  node_localstore[("Local projects<br/>[projectStorage.ts]")]
  node_boq["Cost estimate<br/>[boqEngine.ts]"]
  node_blueprint["Blueprint export<br/>[blueprintExport.ts]"]
  node_schedule["Design schedule<br/>[designSchedule.ts]"]
end

node_owner(("Plot owner"))

node_owner -->|"enters requirements"| node_page
node_page -->|"opens controls"| node_studio
node_page -->|"requests layout"| node_solvehook
node_solvehook -->|"sends constraints"| node_solveclient
node_solveclient -->|"POST /solve"| node_api
node_api -->|"solves layout"| node_solver
node_page -->|"submits prompt"| node_ai_prompt_client
node_ai_prompt_client -->|"requests plan"| node_api
node_api -->|"resolves prompt"| node_promptplan
node_page -->|"submits image"| node_ai_image_client
node_ai_image_client -->|"requests analysis"| node_api
node_api -->|"parses plan image"| node_ai_plan
node_api -->|"analyzes facade"| node_ai_facade
node_solver -->|"enforces access"| node_connectivity
node_solver -->|"adds constraints"| node_realism
node_solver -->|"applies zoning"| node_zoning
node_api -->|"derives quantities"| node_quantities
node_solvehook -->|"provides layout"| node_scene
node_page -->|"renders design"| node_scene
node_scene -->|"uses movement rules"| node_walkthrough
node_scene -->|"applies finishes"| node_materials
node_scene -->|"builds furniture meshes"| node_furniture
node_page -->|"loads and saves"| node_localstore
node_page -->|"estimates cost"| node_boq
node_page -->|"exports blueprint"| node_blueprint
node_page -->|"creates schedule"| node_schedule

click node_page "https://github.com/r3nesh/root/blob/main/frontend/app/page.tsx"
click node_studio "https://github.com/r3nesh/root/blob/main/frontend/components/TopRibbonTaskbar.tsx"
click node_solvehook "https://github.com/r3nesh/root/blob/main/frontend/lib/useSolve.ts"
click node_solveclient "https://github.com/r3nesh/root/blob/main/frontend/lib/solve.ts"
click node_ai_prompt_client "https://github.com/r3nesh/root/blob/main/frontend/lib/aiPlan.ts"
click node_ai_image_client "https://github.com/r3nesh/root/blob/main/frontend/lib/aiPlanImage.ts"
click node_api "https://github.com/r3nesh/root/blob/main/backend/api/main.py"
click node_promptplan "https://github.com/r3nesh/root/blob/main/backend/prompt_to_plan.py"
click node_ai_plan "https://github.com/r3nesh/root/blob/main/backend/ai/plan_from_image.py"
click node_ai_facade "https://github.com/r3nesh/root/blob/main/backend/ai/facade_from_image.py"
click node_solver "https://github.com/r3nesh/root/blob/main/backend/solver/model.py"
click node_connectivity "https://github.com/r3nesh/root/blob/main/backend/solver/connectivity.py"
click node_realism "https://github.com/r3nesh/root/blob/main/backend/solver/realism.py"
click node_zoning "https://github.com/r3nesh/root/blob/main/backend/zoning.py"
click node_quantities "https://github.com/r3nesh/root/blob/main/backend/solver/quantities.py"
click node_localstore "https://github.com/r3nesh/root/blob/main/frontend/lib/projectStorage.ts"
click node_scene "https://github.com/r3nesh/root/blob/main/frontend/components/Scene.tsx"
click node_walkthrough "https://github.com/r3nesh/root/blob/main/frontend/lib/walkthrough.ts"
click node_materials "https://github.com/r3nesh/root/blob/main/frontend/lib/materialsCatalog.ts"
click node_furniture "https://github.com/r3nesh/root/blob/main/frontend/lib/aiFurnitureEngine.ts"
click node_boq "https://github.com/r3nesh/root/blob/main/frontend/lib/boqEngine.ts"
click node_blueprint "https://github.com/r3nesh/root/blob/main/frontend/lib/blueprintExport.ts"
click node_schedule "https://github.com/r3nesh/root/blob/main/frontend/lib/designSchedule.ts"

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_page,node_studio,node_solvehook toneBlue
class node_solveclient,node_ai_prompt_client,node_ai_image_client,node_api,node_promptplan,node_ai_plan,node_ai_facade,node_solver,node_connectivity,node_realism,node_zoning,node_quantities toneAmber
class node_scene,node_walkthrough,node_materials,node_furniture toneMint
class node_localstore,node_boq,node_blueprint,node_schedule toneRose
class node_owner toneIndigo
```

## Components

### Design interface

- [Design workspace](https://github.com/r3nesh/root/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Design controls](https://github.com/r3nesh/root/blob/main/frontend/components/TopRibbonTaskbar.tsx): `frontend/components/TopRibbonTaskbar.tsx`
- [Solve state](https://github.com/r3nesh/root/blob/main/frontend/lib/useSolve.ts): `frontend/lib/useSolve.ts`

### Plan generation

- [Solve client](https://github.com/r3nesh/root/blob/main/frontend/lib/solve.ts): `frontend/lib/solve.ts`
- [Prompt planning](https://github.com/r3nesh/root/blob/main/frontend/lib/aiPlan.ts): `frontend/lib/aiPlan.ts`
- [Plan image input](https://github.com/r3nesh/root/blob/main/frontend/lib/aiPlanImage.ts): `frontend/lib/aiPlanImage.ts`
- [FastAPI endpoints](https://github.com/r3nesh/root/blob/main/backend/api/main.py): `backend/api/main.py`
- [Prompt resolver](https://github.com/r3nesh/root/blob/main/backend/prompt_to_plan.py): `backend/prompt_to_plan.py`
- [AI plan parsing](https://github.com/r3nesh/root/blob/main/backend/ai/plan_from_image.py): `backend/ai/plan_from_image.py`
- [Facade analysis](https://github.com/r3nesh/root/blob/main/backend/ai/facade_from_image.py): `backend/ai/facade_from_image.py`
- [CP-SAT layout](https://github.com/r3nesh/root/blob/main/backend/solver/model.py): `backend/solver/model.py`
- [Room connectivity](https://github.com/r3nesh/root/blob/main/backend/solver/connectivity.py): `backend/solver/connectivity.py`
- [Plan realism](https://github.com/r3nesh/root/blob/main/backend/solver/realism.py): `backend/solver/realism.py`
- [Zoning rules](https://github.com/r3nesh/root/blob/main/backend/zoning.py): `backend/zoning.py`
- [Plan quantities](https://github.com/r3nesh/root/blob/main/backend/solver/quantities.py): `backend/solver/quantities.py`

### 3D design

- [3D scene](https://github.com/r3nesh/root/blob/main/frontend/components/Scene.tsx): `frontend/components/Scene.tsx`
- [Walkthrough controls](https://github.com/r3nesh/root/blob/main/frontend/lib/walkthrough.ts): `frontend/lib/walkthrough.ts`
- [Materials and models](https://github.com/r3nesh/root/blob/main/frontend/lib/materialsCatalog.ts): `frontend/lib/materialsCatalog.ts`
- [Procedural furniture](https://github.com/r3nesh/root/blob/main/frontend/lib/aiFurnitureEngine.ts): `frontend/lib/aiFurnitureEngine.ts`

### Project outputs

- [Local projects](https://github.com/r3nesh/root/blob/main/frontend/lib/projectStorage.ts): `frontend/lib/projectStorage.ts`
- [Cost estimate](https://github.com/r3nesh/root/blob/main/frontend/lib/boqEngine.ts): `frontend/lib/boqEngine.ts`
- [Blueprint export](https://github.com/r3nesh/root/blob/main/frontend/lib/blueprintExport.ts): `frontend/lib/blueprintExport.ts`
- [Design schedule](https://github.com/r3nesh/root/blob/main/frontend/lib/designSchedule.ts): `frontend/lib/designSchedule.ts`

### Other components

- **Plot owner**

## Connections

- Plot owner → Design workspace: enters requirements
- Design workspace → Design controls: opens controls
- Design workspace → Solve state: requests layout
- Solve state → Solve client: sends constraints
- Solve client → FastAPI endpoints: POST /solve
- FastAPI endpoints → CP-SAT layout: solves layout
- Design workspace → Prompt planning: submits prompt
- Prompt planning → FastAPI endpoints: requests plan
- FastAPI endpoints → Prompt resolver: resolves prompt
- Design workspace → Plan image input: submits image
- Plan image input → FastAPI endpoints: requests analysis
- FastAPI endpoints → AI plan parsing: parses plan image
- FastAPI endpoints → Facade analysis: analyzes facade
- CP-SAT layout → Room connectivity: enforces access
- CP-SAT layout → Plan realism: adds constraints
- CP-SAT layout → Zoning rules: applies zoning
- FastAPI endpoints → Plan quantities: derives quantities
- Solve state → 3D scene: provides layout
- Design workspace → 3D scene: renders design
- 3D scene → Walkthrough controls: uses movement rules
- 3D scene → Materials and models: applies finishes
- 3D scene → Procedural furniture: builds furniture meshes
- Design workspace → Local projects: loads and saves
- Design workspace → Cost estimate: estimates cost
- Design workspace → Blueprint export: exports blueprint
- Design workspace → Design schedule: creates schedule