How navarro-n/portfolio-react works
Qué tipo de proyecto es y para qué sirve (según árbol + README)
Tipo: aplicación frontend pura (SPA) hecha con React + Vite.
Propósito: portfolio personal con una UI tipo “escritorio” (desktop metaphor) con iconos y ventanas (About, Projects, PDF/CV, Calculator, etc.).
Backend: explícitamente no hay (“frontend puro, sin backend”).
Datos: provienen de ficheros locales en src/data/* (no hay API, no hay DB).
Esto determina cómo debe verse un diagrama “preciso”: no es una arquitectura cliente-servidor clásica, sino una arquitectura de UI por capas (entrypoint → layout → desktop → window manager/ventanas → componentes) más una capa de build tooling (Vite/Tailwind/PostCSS).
Cómo leer la estructura del repo (y cómo convertirla en componentes del diagrama)
Tu “mapa” real está prácticamente todo en portolio-react/src:
Entry / Bootstrap
• src/main.jsx: punto de entrada React (createRoot, mounting).
• src/index.css: estilos globales.
• src/app/App.jsx + src/app/App.css: raíz de la app (componente top-level).
Sistema (chrome / UI shell)
• src/system/Header/*
• src/system/Footer/*
Esto es el “marco” persistente, separado del contenido.
“Desktop” (workspace)
• src/desktop/Desktop.jsx + .module.css: área principal donde viven los iconos y se abren las ventanas.
Iconos (launcher)
• src/data/desktopIcons.js: modelo de iconos (labels, ids, qué ventana abren, etc.).
Ventanas (core UX del portfolio)
• src/windows/Window.jsx + .module.css: componente genérico de ventana (título, close, drag, z-index, etc.).
• Ventanas concretas:
• AboutWindow.jsx
• ProjectsWindow.jsx (+ .module.css)
• PdfWindow.jsx (abre public/cv_Irene-Pinillos-Navarro.pdf)
• CalculatorWindow.jsx (+ .module.css)
• Componente app dentro de ventana:
• src/components/Calculator/Calculator.jsx (+ .module.css)
Hooks (interacción clave del desktop)
• src/hooks/useDoubleClick.js: interacción para abrir iconos con doble click.
• src/hooks/useDrag.js: interacción para arrastrar ventanas o elementos.
Datos estáticos (contenido del portfolio)
• src/data/projects.js: listado de proyectos.
• src/data/themes.js: temas / estilos.
• src/data/desktopIcons.js: iconos del “escritorio”.
Build / Tooling / Config (no runtime, pero sí arquitectura de entrega)
• vite.config.js: bundling/dev server.
• tailwind.config.js, postcss.config.cjs: pipeline CSS (aunque usas mucho CSS Modules).
• eslint.config.js: calidad/lint.
• index.html: template base Vite.
• public/cv_*.pdf: asset servido estáticamente (sin import, vía URL).
Qué diagramas dibujar para que sea “lo más exacto” (y no quedarte corto)
Para este proyecto conviene 2 niveles (mínimo) y 3 si quieres máxima precisión:
Diagrama “Container / Deployment” (estilo C4 – nivel contenedor)
En este caso “containers” no son microservicios; son bloques de entrega:
Nodos recomendados:
Static Hosting / Web Server (opcional en tu repo, pero real en producción)
• Sirve index.html, assets/*.js/*.css, y public/cv_*.pdf
React SPA (Portfolio React)
• Renderiza UI, maneja estado y eventos
Build Toolchain (Vite + Node + npm) (como “offline/build-time”)
• Produce el bundle estático
Flechas clave:
• User → Browser: interacción (click/doble click/drag).
• Browser → Static Hosting: GET index.html, *.js, *.css, cv.pdf.
• Browser ↔ React SPA: render y event loop.
• Dev Machine → Vite Dev Server (en dev): HMR/serving.
> Nota: Como no hay backend ni API, no dibujes DB/REST/GraphQL salvo como “none / not present”.
Diagrama “Component / Runtime architecture” (lo más importante aquí)
Este es el diagrama donde capturas la arquitectura real: jerarquía y dependencias de componentes.
Backbone recomendado (cajas grandes):
• main.jsx (Bootstrap)
→ App (Root)
→ DesktopLayout
→ Header
→ Desktop
→ DesktopIcon (N instancias, desde desktopIcons.js)
→ Window (contenedor común)
→ AboutWindow / ProjectsWindow / PdfWindow / CalculatorWindow
→ (en CalculatorWindow) Calculator
→ Footer
Módulos de soporte (en cajas laterales):
• hooks/useDoubleClick usado por DesktopIcon (o Desktop).
• hooks/useDrag usado por Window (o ventanas).
• data/projects, data/themes, data/desktopIcons consumidos por ventanas/layout/desktop.
• public/cv_*.pdf consumido por PdfWindow (URL directa).
Flechas importantes (dirección = “depende de / usa”):
• Desktop → desktopIcons.js (para mapear iconos)
• DesktopIcon → useDoubleClick (para abrir)
• Window → useDrag (para mover)
• ProjectsWindow → projects.js
• App o Desktop → “Window State” (estado de ventanas abiertas, foco, z-index)
> Aquí es donde debes “separar en tantos componentes como sea posible”: cada carpeta top-level en src/ es un bloque. Dentro de windows/ y system/ conviene detallar cada ventana/componente.
Diagrama “State & Event Flow” (muy útil para esta UI)
Este proyecto tiene una interacción tipo desktop; aunque no haya backend, sí hay flujos:
Eventos:
• Doble click en DesktopIcon
• Drag en Window (mouse down/move/up)
• Close window
Estado típico a dibujar (aunque no veamos el código exacto, el diagrama debe reservarlo):
• openWindows[] (qué ventanas están abiertas)
• activeWindowId (foco)
• zIndexMap (orden de apilado)
• windowPositions (x,y por ventana)
• theme (si aplica desde themes.js)
Flechas:
• User action → Component event handler → Hook (si aplica) → setState → re-render → UI update
Esto hace que el diagrama sea “arquitectura real” y no solo un árbol de componentes.
Patrones/diseño arquitectónico presentes (y cómo reflejarlos)
• UI Shell + Workspace pattern: Header/Footer (shell) + Desktop (workspace).
• Window Manager pattern (implícito): Window.jsx como primitive reusable + ventanas concretas como contenido.
• Presentational vs Data modules: src/data/* como fuente de contenido estático (sin fetch).
• Custom hooks para interacción avanzada: useDrag, useDoubleClick como capa reutilizable de comportamiento.
En el diagrama, marca estos como “primitives” o “shared behavior”.
Qué tecnologías etiquetar explícitamente en el diagrama
Como es frontend-only, sí compensa etiquetar:
• React (UI runtime)
• Vite (build + dev server)
• CSS Modules (aparece en muchos *.module.css)
• Tailwind/PostCSS (por configs; aunque no se vea en el árbol de CSS, existe el pipeline)
• Static assets desde public/ (PDF CV)
Convenciones visuales (para que el diagrama sea claro y “engineering-grade”)
• Azul: componentes React (App/Layout/Desktop/Windows)
• Gris: módulos de soporte (hooks, data)
• Verde: assets estáticos (public/cv...pdf)
• Naranja: tooling/build (Vite, PostCSS, Tailwind, ESLint)
• (Opcional) Borde punteado para “build-time only” vs borde sólido “runtime”.
Etiquetado mínimo por caja:
• Nombre del módulo (Window.jsx)
• Rol (“Generic window container”, “Static data source”)
• Inputs/outputs si aplica (ej: projects.js → ProjectsWindow)
Flechas:
• Sólida: “import/uses”
• Discontinua: “served as asset” o “builds into”
• Flechas con texto para eventos: “double click”, “drag”, “close”.
En windows/, separa
• Window (primitiva)
• ventanas específicas (About/Projects/Pdf/Calculator)
Añade un bloque “State (Window Manager)” aunque no haya store dedicado
• dónde vive el estado (App o Desktop) y qué gestiona.
Añade “Toolchain” (Vite/Tailwind/PostCSS) como capa build-time.
7. Verifica que no aparece ninguna caja de API/DB (porque el README dice que no hay backend).
Plantilla rápida (estructura final sugerida del diagrama)
Nivel 1:
• User → Browser
• Browser → Static Hosting (serves SPA + PDF)
• Browser runs React SPA
Nivel 2 (dentro de “React SPA”):
• main.jsx → App → DesktopLayout
• Header
• Desktop
• DesktopIcon (uses useDoubleClick, reads desktopIcons)
• Window (uses useDrag)
• AboutWindow
• ProjectsWindow (reads projects)
• PdfWindow (opens /cv.pdf)
• CalculatorWindow → Calculator
• Footer
• Side modules: data/*, hooks/*, styles (CSS Modules/global)
Con esto capturas el 95% de la arquitectura real del repo, sin inventarte backend, y separando el sistema en la máxima cantidad de componentes útiles.