How rigoloberto/morehousedecoria works
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: App.vue App shell · index.ts API server · main.ts Vue app · index.css Styling
Components 16
Frontend SPA
Vue 3 single-page app for staging, browsing history, and quote actions.
- Vue app · Client entry and app shell for the staging workflow.
frontend/src/main.ts - App shell · Main UI container coordinating views and interactions.
frontend/src/App.vue - Timeline · Sidebar history for Original, Etapa 1, Etapa 2, and restores.
- Lightbox · Modal gallery for enlarged renders, navigation, and thumbnails.
- Quote cart · Running product total accumulated from staged iterations.
- Admin panel · Restricted catalog management and prioritization workflow.
- Styling · 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 · Main backend entrypoint for the app and AI orchestration.
backend/src/index.ts - Diagnostics · Separate development and provider-checking process on port 3001.
backend/src/dev.ts - Staging flow · Coordinates upload, prompt, references, and iterative turn creation.
- Iteration data · Structured prompt, evaluation, furniture, and render metadata per turn.
- Catalog data · Furniture items used by the AI and admin management path.
- Gemini rewrite · Rewrites requests to preserve references when Gemini quota is exhausted.
- FLUX.2 · Primary image generation target with multi-reference input support.
- HF fallback · Secondary generation path using FLUX.1-schnell when free quota is exceeded.
- Env config · Backend environment variables for API access, quotas, and ports.
Connections 18
- 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.