# rigoloberto/morehousedecoria architecture

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

- Interactive diagram: https://gitdiagram.com/rigoloberto/morehousedecoria
- Repository: https://github.com/rigoloberto/morehousedecoria

## Overview

1. **Repository shape**
   - The repo is a two-tier TypeScript app: a **Bun-based backend** in `backend/` and a **Vue 3 frontend** in `frontend/`.
   - There is no separate database, queue, or worker project visible in the tree, so the architecture is centered on a single API server plus a single-page client.

2. **Frontend boundary**
   - `frontend/src/main.ts` boots the app, and `frontend/src/App.vue` is the main UI shell.
   - Styling is handled with **Tailwind CSS** and PostCSS, with a shared stylesheet in `src/assets/index.css`.
   - The frontend is a Vite-powered SPA responsible for the user-facing staging workflow, timeline, lightbox viewer, quote cart, and admin panel mentioned in the README.

3. **Backend boundary**
   - `backend/src/index.ts` is the main server entrypoint.
   - `backend/src/dev.ts` appears to provide a separate development/diagnostic process, matching the README’s “diagnóstico” server on port 3001.
   - The backend is the integration layer between the UI and external AI services.

4. **Primary user flow**
   - A user uploads a room image, chooses catalog products or writes a free-text instruction, and submits a staging “turn.”
   - The frontend sends the room image plus chosen references/prompt to the backend.
   - The backend orchestrates AI generation and returns a newly staged render for the current iteration.

5. **AI generation pipeline**
   - The core generation target is **Cloudflare Workers AI FLUX.2** with multi-reference image support (`input_image_1..3` per the README).
   - If Gemini quotas are exhausted, the backend dynamically rewrites the request into an English prompt that preserves the image references and catalog intent.
   - If Cloudflare’s free quota is exceeded, the backend transparently falls back to **Hugging Face FLUX.1-schnell**.

6. **Iteration model**
   - The app is built around sequential design stages: `Original` → `Etapa 1` → `Etapa 2` → etc.
   - Each turn creates a new history entry rather than overwriting the previous design.
   - The user can restore any prior iteration as the active base, so the design history functions like a branching timeline.

7. **UI subsystems**
   - The **sidebar timeline** is the main navigation for iteration history.
   - The **lightbox/modal gallery** provides enlarged viewing of renders, with previous/next navigation and thumbnails.
   - The UI also exposes the AI evaluation, exact prompt, and furniture used per iteration, which implies the backend returns structured metadata alongside the generated image.

8. **Quote/cart subsystem**
   - The quote cart accumulates all products added across the active session’s turns.
   - This is a derived view of the staged design history: each iteration contributes items, and the frontend computes the running total.
   - The “request full quote” action likely sends the accumulated catalog selection back to the backend or an external fulfillment flow.

9. **Catalog/admin boundary**
   - The README describes an **Administrador** panel with hardcoded test credentials, suggesting a distinct admin-only UI path.
   - That panel is used to add, edit, or delete furniture items and influence which products the AI prioritizes.
   - Because no separate service is present in the tree, the catalog management data is likely served by the backend itself or stored locally within the app’s backend state/data layer.

10. **Diagnostics and operational concerns**
   - The project explicitly separates the main app server from a **model/API diagnostics server** on port 3001.
   - This indicates a deliberate operational boundary for checking quota/state of Gemini, Cloudflare Workers AI, and Hugging Face independently from the main user flow.

11. **Runtime and tooling**
   - Both halves use **Bun** for dependency management and execution.
   - The frontend runs through **Vite**, while the backend is a Bun TypeScript service.
   - Environment variables in `backend/.env` are the main configuration surface for external API access and port selection.

12. **Architecture summary**
   - Conceptually, the system is: **Vue SPA for design interaction** → **Bun API server for orchestration** → **external AI providers for recommendation and image generation**.
   - The main data products are: staged render images, iteration metadata, selected catalog items, and accumulated quote totals.

Main entry points: [`frontend/src/App.vue`](https://github.com/rigoloberto/morehousedecoria/blob/main/frontend/src/App.vue) (App shell), [`backend/src/index.ts`](https://github.com/rigoloberto/morehousedecoria/blob/main/backend/src/index.ts) (API server), [`frontend/src/main.ts`](https://github.com/rigoloberto/morehousedecoria/blob/main/frontend/src/main.ts) (Vue app), [`frontend/src/assets/index.css`](https://github.com/rigoloberto/morehousedecoria/blob/main/frontend/src/assets/index.css) (Styling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_spa["Vue app<br/>vite spa<br/>[main.ts]"]
  node_app_shell["App shell<br/>vue shell<br/>[App.vue]"]
  node_timeline(("Timeline<br/>iteration nav"))
  node_viewer(("Lightbox<br/>image viewer"))
  node_cart[("Quote cart<br/>derived cart")]
  node_admin_ui["Admin panel<br/>admin ui"]
  node_styles["Styling<br/>tailwind css<br/>[index.css]"]
end

subgraph group_backend["Backend API"]
  node_backend_api["API server<br/>bun server<br/>[index.ts]"]
  node_diagnostics["Diagnostics<br/>dev server<br/>[dev.ts]"]
  node_staging_flow(("Staging flow<br/>request orchestration"))
  node_metadata["Iteration data<br/>history model"]
  node_catalog[("Catalog data<br/>product store")]
  node_gemini_adapter{{"Gemini rewrite<br/>prompt adapter"}}
  node_cloudflare_ai["FLUX.2<br/>image generation"]
  node_hf_fallback["HF fallback<br/>image fallback"]
  node_env["Env config<br/>runtime config"]
end

node_spa -->|"boots"| node_app_shell
node_app_shell -->|"navigates"| node_timeline
node_app_shell -->|"opens"| node_viewer
node_app_shell -->|"summarizes"| node_cart
node_app_shell -->|"routes"| node_admin_ui
node_spa -->|"styles"| node_styles
node_backend_api -->|"orchestrates"| node_staging_flow
node_staging_flow -->|"generates"| node_cloudflare_ai
node_staging_flow -->|"rewrites"| node_gemini_adapter
node_staging_flow -->|"falls back"| node_hf_fallback
node_staging_flow -->|"returns"| node_metadata
node_staging_flow -->|"uses"| node_catalog
node_backend_api -.->|"separates"| node_diagnostics
node_backend_api -->|"reads"| node_env
node_catalog -->|"edited by"| node_admin_ui
node_metadata -->|"drives"| node_timeline
node_metadata -->|"describes"| node_viewer
node_metadata -->|"feeds"| node_cart

click node_spa "https://github.com/rigoloberto/morehousedecoria/blob/main/frontend/src/main.ts"
click node_app_shell "https://github.com/rigoloberto/morehousedecoria/blob/main/frontend/src/App.vue"
click node_styles "https://github.com/rigoloberto/morehousedecoria/blob/main/frontend/src/assets/index.css"
click node_backend_api "https://github.com/rigoloberto/morehousedecoria/blob/main/backend/src/index.ts"
click node_diagnostics "https://github.com/rigoloberto/morehousedecoria/blob/main/backend/src/dev.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_spa,node_app_shell,node_timeline,node_viewer,node_cart,node_admin_ui,node_styles toneBlue
class node_backend_api,node_diagnostics,node_staging_flow,node_metadata,node_catalog,node_gemini_adapter,node_cloudflare_ai,node_hf_fallback,node_env toneAmber
```

## Components

### Frontend SPA

Vue 3 single-page app for staging, browsing history, and quote actions.

- [Vue app](https://github.com/rigoloberto/morehousedecoria/blob/main/frontend/src/main.ts): vite spa · Client entry and app shell for the staging workflow. · `frontend/src/main.ts`
- [App shell](https://github.com/rigoloberto/morehousedecoria/blob/main/frontend/src/App.vue): vue shell · Main UI container coordinating views and interactions. · `frontend/src/App.vue`
- **Timeline**: iteration nav · Sidebar history for Original, Etapa 1, Etapa 2, and restores.
- **Lightbox**: image viewer · Modal gallery for enlarged renders, navigation, and thumbnails.
- **Quote cart**: derived cart · Running product total accumulated from staged iterations.
- **Admin panel**: admin ui · Restricted catalog management and prioritization workflow.
- [Styling](https://github.com/rigoloberto/morehousedecoria/blob/main/frontend/src/assets/index.css): tailwind css · Shared stylesheet and utility-driven presentation layer. · `frontend/src/assets/index.css`

### Backend API

Bun TypeScript server for orchestration, diagnostics, and provider access.

- [API server](https://github.com/rigoloberto/morehousedecoria/blob/main/backend/src/index.ts): bun server · Main backend entrypoint for the app and AI orchestration. · `backend/src/index.ts`
- [Diagnostics](https://github.com/rigoloberto/morehousedecoria/blob/main/backend/src/dev.ts): dev server · Separate development and provider-checking process on port 3001. · `backend/src/dev.ts`
- **Staging flow**: request orchestration · Coordinates upload, prompt, references, and iterative turn creation.
- **Iteration data**: history model · Structured prompt, evaluation, furniture, and render metadata per turn.
- **Catalog data**: product store · Furniture items used by the AI and admin management path.
- **Gemini rewrite**: prompt adapter · Rewrites requests to preserve references when Gemini quota is exhausted.
- **FLUX.2**: image generation · Primary image generation target with multi-reference input support.
- **HF fallback**: image fallback · Secondary generation path using FLUX.1-schnell when free quota is exceeded.
- **Env config**: runtime config · Backend environment variables for API access, quotas, and ports.

## Connections

- Vue app → App shell: boots · Frontend entry mounts the main application shell.
- App shell → Timeline: navigates · Shell exposes iteration history as the primary navigation.
- App shell → Lightbox: opens · Shell launches the render lightbox for detailed viewing.
- App shell → Quote cart: summarizes · Shell shows accumulated quote items and totals.
- App shell → Admin panel: routes · Shell exposes the admin-only catalog path.
- Vue app → Styling: styles · SPA imports shared styling and Tailwind-driven presentation.
- API server → Staging flow: orchestrates · Main server coordinates the staging request lifecycle.
- Staging flow → FLUX.2: generates · Primary generation path sends prompts and reference images to FLUX.2.
- Staging flow → Gemini rewrite: rewrites · Fallback prompt rewriting preserves catalog intent and image references.
- Staging flow → HF fallback: falls back · Secondary generation path handles Cloudflare free-quota exhaustion.
- Staging flow → Iteration data: returns · Generation responses include structured iteration metadata.
- Staging flow → Catalog data: uses · Prompting and quote views depend on catalog items.
- API server → Diagnostics: separates · Operationally distinct server for provider and quota diagnostics.
- API server → Env config: reads · Backend loads API keys, quotas, and port settings from environment.
- Catalog data → Admin panel: edited by · Admin UI adds, edits, and deletes furniture records.
- Iteration data → Timeline: drives · Iteration records power the history sidebar and restore actions.
- Iteration data → Lightbox: describes · Metadata supplies prompt, evaluation, and furniture details for each render.
- Iteration data → Quote cart: feeds · Cart totals are derived from items accumulated across iterations.