# talmastera/hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/talmastera/hackathon
- Repository: https://github.com/talmastera/hackathon

## Overview

FitIn is a bilingual, browser-based furniture-layout editor. Users select a built-in plan or trace their own, edit furniture in a shared 2D/3D workspace, and inspect fit issues; optional tools provide rule-based layout proposals and AI-generated furniture appearance. Geometry, measurements, and checks run locally. The graph preserves the documented workflows and major capabilities; several feature links are documented in the README but their implementation was not sampled, so those links cite the README rather than implying source inspection.

Main entry points: [`src/features/flat-editor/workspace.tsx`](https://github.com/talmastera/hackathon/blob/main/src/features/flat-editor/workspace.tsx) (Editor workspace), [`src/features/floor-trace/review-step.tsx`](https://github.com/talmastera/hackathon/blob/main/src/features/floor-trace/review-step.tsx) (Trace review), [`src/features/design-assistant/assistant-panel.tsx`](https://github.com/talmastera/hackathon/blob/main/src/features/design-assistant/assistant-panel.tsx) (Assistant panel), [`src/features/model-looks/look-panel.tsx`](https://github.com/talmastera/hackathon/blob/main/src/features/model-looks/look-panel.tsx) (Look controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Layout workspace"]
  node_workspace["Editor workspace<br/>[workspace.tsx]"]
  node_presets["Plan presets<br/>[flat-preset.ts]"]
  node_editor_state["Layout state<br/>[state.ts]"]
  node_plan_view["2D floor plan<br/>[floor-plan.tsx]"]
  node_scene_view["3D room scene<br/>[room-scene.tsx]"]
  node_furniture_mesh["Furniture models<br/>[furniture-mesh.tsx]"]
  node_source_panel["Plan source panel<br/>[source-panel.tsx]"]
end

subgraph group_trace["Plan tracing"]
  node_trace_ui["Trace review<br/>[review-step.tsx]"]
  node_trace_flow["Trace workflow<br/>[trace-state.ts]"]
  node_floorplan_client["Plan reader client"]
  node_floorplan_api["Plan reading API<br/>[route.ts]"]
  node_trace_model["Trace model<br/>[trace.ts]"]
end

subgraph group_geometry["Geometry and checks"]
  node_geometry_arch["Flat architecture<br/>[architecture.ts]"]
  node_geometry_layout["Layout checks<br/>[layout.ts]"]
  node_geometry_oriented["Oriented footprints<br/>[oriented.ts]"]
  node_geometry_polygon["Polygon operations<br/>[polygon.ts]"]
end

subgraph group_assistant["Design assistant"]
  node_assistant_ui["Assistant panel"]
  node_assistant_context["Room context<br/>[context.ts]"]
  node_assistant_session["Proposal session<br/>[session.ts]"]
end

subgraph group_looks["3D looks"]
  node_looks_ui["Look controls<br/>[look-panel.tsx]"]
  node_looks_state["Look state<br/>[looks.ts]"]
  node_looks_client["Model generation client<br/>[model3d-client.ts]"]
  node_model_api["3D model API<br/>[route.ts]"]
  node_fal_service["fal.ai generation<br/>[fal-server.ts]"]
end

node_user(("Household user"))

node_user -->|"edits layout"| node_workspace
node_workspace -->|"selects plan"| node_presets
node_workspace -->|"updates state"| node_editor_state
node_workspace -->|"renders plan"| node_plan_view
node_workspace -->|"renders scene"| node_scene_view
node_workspace -->|"shows source"| node_source_panel
node_plan_view -->|"draws architecture"| node_geometry_arch
node_scene_view -->|"renders furniture"| node_furniture_mesh
node_user -->|"traces flat"| node_trace_ui
node_trace_ui -->|"edits trace"| node_trace_model
node_trace_ui -.->|"uses workflow"| node_trace_flow
node_trace_flow -.->|"requests reading"| node_floorplan_client
node_floorplan_client -.->|"posts plan"| node_floorplan_api
node_floorplan_api -->|"validates type"| node_trace_model
node_trace_model -->|"simplifies polygons"| node_geometry_polygon
node_geometry_arch -->|"uses footprints"| node_geometry_oriented
node_geometry_polygon -->|"uses polygon helpers"| node_geometry_oriented
node_editor_state -.->|"checks fit"| node_geometry_layout
node_user -->|"requests proposal"| node_assistant_ui
node_assistant_ui -->|"builds context"| node_assistant_context
node_assistant_ui -.->|"manages proposal"| node_assistant_session
node_assistant_session -->|"applies accepted moves"| node_editor_state
node_user -->|"requests appearance"| node_looks_ui
node_looks_ui -->|"manages looks"| node_looks_state
node_looks_state -->|"supplies appearance"| node_furniture_mesh
node_looks_ui -.->|"starts generation"| node_looks_client
node_looks_client -.->|"posts photo"| node_model_api
node_model_api -.->|"requests generation"| node_fal_service

click node_workspace "https://github.com/talmastera/hackathon/blob/main/src/features/flat-editor/workspace.tsx"
click node_presets "https://github.com/talmastera/hackathon/blob/main/src/data/flat-preset.ts"
click node_editor_state "https://github.com/talmastera/hackathon/blob/main/src/features/flat-editor/state.ts"
click node_plan_view "https://github.com/talmastera/hackathon/blob/main/src/components/plan/floor-plan.tsx"
click node_scene_view "https://github.com/talmastera/hackathon/blob/main/src/components/scene/room-scene.tsx"
click node_furniture_mesh "https://github.com/talmastera/hackathon/blob/main/src/components/scene/furniture-mesh.tsx"
click node_source_panel "https://github.com/talmastera/hackathon/blob/main/src/components/source-panel.tsx"
click node_trace_ui "https://github.com/talmastera/hackathon/blob/main/src/features/floor-trace/review-step.tsx"
click node_trace_flow "https://github.com/talmastera/hackathon/blob/main/src/features/floor-trace/trace-state.ts"
click node_floorplan_client "https://github.com/talmastera/hackathon/blob/main/src/features/floor-trace/floorplan-client.ts"
click node_floorplan_api "https://github.com/talmastera/hackathon/blob/main/src/app/api/floorplan/route.ts"
click node_trace_model "https://github.com/talmastera/hackathon/blob/main/src/lib/floorplan/trace.ts"
click node_geometry_arch "https://github.com/talmastera/hackathon/blob/main/src/lib/geometry/architecture.ts"
click node_geometry_layout "https://github.com/talmastera/hackathon/blob/main/src/lib/geometry/layout.ts"
click node_geometry_oriented "https://github.com/talmastera/hackathon/blob/main/src/lib/geometry/oriented.ts"
click node_geometry_polygon "https://github.com/talmastera/hackathon/blob/main/src/lib/geometry/polygon.ts"
click node_assistant_ui "https://github.com/talmastera/hackathon/blob/main/src/features/design-assistant/assistant-panel.tsx"
click node_assistant_context "https://github.com/talmastera/hackathon/blob/main/src/features/design-assistant/context.ts"
click node_assistant_session "https://github.com/talmastera/hackathon/blob/main/src/features/design-assistant/session.ts"
click node_looks_ui "https://github.com/talmastera/hackathon/blob/main/src/features/model-looks/look-panel.tsx"
click node_looks_state "https://github.com/talmastera/hackathon/blob/main/src/features/model-looks/looks.ts"
click node_looks_client "https://github.com/talmastera/hackathon/blob/main/src/features/model-looks/model3d-client.ts"
click node_model_api "https://github.com/talmastera/hackathon/blob/main/src/app/api/model3d/route.ts"
click node_fal_service "https://github.com/talmastera/hackathon/blob/main/src/lib/model3d/fal-server.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_workspace,node_presets,node_editor_state,node_plan_view,node_scene_view,node_furniture_mesh,node_source_panel,node_user toneBlue
class node_trace_ui,node_trace_flow,node_floorplan_client,node_floorplan_api,node_trace_model toneAmber
class node_geometry_arch,node_geometry_layout,node_geometry_oriented,node_geometry_polygon toneMint
class node_assistant_ui,node_assistant_context,node_assistant_session toneRose
class node_looks_ui,node_looks_state,node_looks_client,node_model_api,node_fal_service toneIndigo
```

## Components

### Layout workspace

- [Editor workspace](https://github.com/talmastera/hackathon/blob/main/src/features/flat-editor/workspace.tsx): `src/features/flat-editor/workspace.tsx`
- [Plan presets](https://github.com/talmastera/hackathon/blob/main/src/data/flat-preset.ts): `src/data/flat-preset.ts`
- [Layout state](https://github.com/talmastera/hackathon/blob/main/src/features/flat-editor/state.ts): `src/features/flat-editor/state.ts`
- [2D floor plan](https://github.com/talmastera/hackathon/blob/main/src/components/plan/floor-plan.tsx): `src/components/plan/floor-plan.tsx`
- [3D room scene](https://github.com/talmastera/hackathon/blob/main/src/components/scene/room-scene.tsx): `src/components/scene/room-scene.tsx`
- [Furniture models](https://github.com/talmastera/hackathon/blob/main/src/components/scene/furniture-mesh.tsx): `src/components/scene/furniture-mesh.tsx`
- [Plan source panel](https://github.com/talmastera/hackathon/blob/main/src/components/source-panel.tsx): `src/components/source-panel.tsx`

### Plan tracing

- [Trace review](https://github.com/talmastera/hackathon/blob/main/src/features/floor-trace/review-step.tsx): `src/features/floor-trace/review-step.tsx`
- [Trace workflow](https://github.com/talmastera/hackathon/blob/main/src/features/floor-trace/trace-state.ts): `src/features/floor-trace/trace-state.ts`
- [Plan reader client](https://github.com/talmastera/hackathon/blob/main/src/features/floor-trace/floorplan-client.ts): `src/features/floor-trace/floorplan-client.ts`
- [Plan reading API](https://github.com/talmastera/hackathon/blob/main/src/app/api/floorplan/route.ts): `src/app/api/floorplan/route.ts`
- [Trace model](https://github.com/talmastera/hackathon/blob/main/src/lib/floorplan/trace.ts): `src/lib/floorplan/trace.ts`

### Geometry and checks

- [Flat architecture](https://github.com/talmastera/hackathon/blob/main/src/lib/geometry/architecture.ts): `src/lib/geometry/architecture.ts`
- [Layout checks](https://github.com/talmastera/hackathon/blob/main/src/lib/geometry/layout.ts): `src/lib/geometry/layout.ts`
- [Oriented footprints](https://github.com/talmastera/hackathon/blob/main/src/lib/geometry/oriented.ts): `src/lib/geometry/oriented.ts`
- [Polygon operations](https://github.com/talmastera/hackathon/blob/main/src/lib/geometry/polygon.ts): `src/lib/geometry/polygon.ts`

### Design assistant

- [Assistant panel](https://github.com/talmastera/hackathon/blob/main/src/features/design-assistant/assistant-panel.tsx): `src/features/design-assistant/assistant-panel.tsx`
- [Room context](https://github.com/talmastera/hackathon/blob/main/src/features/design-assistant/context.ts): `src/features/design-assistant/context.ts`
- [Proposal session](https://github.com/talmastera/hackathon/blob/main/src/features/design-assistant/session.ts): `src/features/design-assistant/session.ts`

### 3D looks

- [Look controls](https://github.com/talmastera/hackathon/blob/main/src/features/model-looks/look-panel.tsx): `src/features/model-looks/look-panel.tsx`
- [Look state](https://github.com/talmastera/hackathon/blob/main/src/features/model-looks/looks.ts): `src/features/model-looks/looks.ts`
- [Model generation client](https://github.com/talmastera/hackathon/blob/main/src/features/model-looks/model3d-client.ts): `src/features/model-looks/model3d-client.ts`
- [3D model API](https://github.com/talmastera/hackathon/blob/main/src/app/api/model3d/route.ts): `src/app/api/model3d/route.ts`
- [fal.ai generation](https://github.com/talmastera/hackathon/blob/main/src/lib/model3d/fal-server.ts): `src/lib/model3d/fal-server.ts`

### Other components

- **Household user**

## Connections

- Household user → Editor workspace: edits layout
- Editor workspace → Plan presets: selects plan (evidence: `src/features/flat-editor/workspace.tsx`)
- Editor workspace → Layout state: updates state (evidence: `src/features/flat-editor/workspace.tsx`)
- Editor workspace → 2D floor plan: renders plan (evidence: `src/features/flat-editor/workspace.tsx`)
- Editor workspace → 3D room scene: renders scene (evidence: `src/features/flat-editor/workspace.tsx`)
- Editor workspace → Plan source panel: shows source (evidence: `src/features/flat-editor/workspace.tsx`)
- 2D floor plan → Flat architecture: draws architecture (evidence: `src/components/plan/floor-plan.tsx`)
- 3D room scene → Furniture models: renders furniture (evidence: `src/components/scene/room-scene.tsx`)
- Household user → Trace review: traces flat
- Trace review → Trace model: edits trace (evidence: `src/features/floor-trace/review-step.tsx`)
- Trace review → Trace workflow: uses workflow (evidence: `src/features/floor-trace/review-step.tsx`)
- Trace workflow → Plan reader client: requests reading
- Plan reader client → Plan reading API: posts plan
- Plan reading API → Trace model: validates type (evidence: `src/app/api/floorplan/route.ts`)
- Trace model → Polygon operations: simplifies polygons (evidence: `src/lib/floorplan/trace.ts`)
- Flat architecture → Oriented footprints: uses footprints (evidence: `src/lib/geometry/architecture.ts`)
- Polygon operations → Oriented footprints: uses polygon helpers (evidence: `src/lib/geometry/polygon.ts`)
- Layout state → Layout checks: checks fit
- Household user → Assistant panel: requests proposal
- Assistant panel → Room context: builds context (evidence: `src/features/design-assistant/context.ts`)
- Assistant panel → Proposal session: manages proposal
- Proposal session → Layout state: applies accepted moves (evidence: `src/features/design-assistant/session.ts`)
- Household user → Look controls: requests appearance
- Look controls → Look state: manages looks
- Look state → Furniture models: supplies appearance (evidence: `src/components/scene/furniture-mesh.tsx`)
- Look controls → Model generation client: starts generation
- Model generation client → 3D model API: posts photo
- 3D model API → fal.ai generation: requests generation (evidence: `src/app/api/model3d/route.ts`)
