# rgraffe/gema-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/rgraffe/gema-frontend
- Repository: https://github.com/rgraffe/gema-frontend

## Overview

##### Project Type and Purpose
- This is a single‐page application (SPA) built with React, TypeScript, and Vite.
- Purpose: provide a frontend UI for managing “grupos de trabajo” (work groups), “técnicos” (technicians), and “ubicaciones técnicas” (technical locations), plus user authentication and access to a static PDF manual.

##### File Structure Analysis
- Top‐level directories and files
- public/ – static assets (PDF manual, favicon, index.html)
- src/ – application source
– components/ – reusable UI pieces (AppSidebar, forms, dialogs, custom UI primitives under ui/)
– pages/ – top‐level route components (Login, VistaGeneral, Canva, Técnicos, UbicacionesTecnicas)
– services/ – HTTP client wrappers for REST endpoints (auth, gruposDeTrabajo, técnicos, ubicacionesTécnicas)
– hooks/ – custom React hooks (e.g. use-mobile)
– validators/ – Zod or similar schemas for form validation
– lib/ – shared utility functions
– types/ – TypeScript type definitions for domain models
– main.tsx / App.tsx – React app entry and root component
- Configuration & build
- vite.config.ts – Vite build and dev‐server setup
- tsconfig*.json – TypeScript configurations
- eslint.config.js – linting rules

##### README Insights
- Minimal template instructions for React+TypeScript in Vite with HMR.
- Mentions two plugin options for React Fast Refresh (Babel or SWC).
- No backend code in repo; services indicate external REST API integration.

1. Developer Environment & Build Toolchain
- Git, ESLint, TypeScript, Vite (dev server, HMR), Build scripts
2. Frontend SPA (Browser)
- React components (pages & ui library), custom hooks, state management
3. HTTP Service Layer (src/services)
- AuthService, TécnicosService, GruposDeTrabajoService, UbicacionesTécnicasService
4. External Backend API
- RESTful endpoints for authentication and CRUD ops
5. Static Assets Server
- public/*.pdf, public/index.html served by Vite in dev or CDN in prod
- Developer → (Git push) → CI/CD pipeline (build) → Deployment
- Vite dev server ↔ Browser (HMR, asset serving)
- Browser → (HTTP requests) → External Backend API
- External Backend API → (JSON responses) → Service Layer → UI components
- UI interactions → form validators → services → API
- Browser → (GET) → static PDF/manual
c. Architectural Patterns & Principles
- Separation of Concerns:
- UI layer (components/pages) vs. data access layer (services) vs. validation layer (validators)
- Componentization & Reusability:
- Atomic design in src/components/ui
- Type Safety & Contracts:
- TypeScript types and Zod schemas ensure consistency
- Dev vs. Prod:
- Vite dev server with HMR vs. optimized build output
d. Key Technologies & Frameworks
- React + React Fast Refresh (Babel or SWC)
- Vite (bundler, dev server)
- TypeScript (types, interfaces)
- ESLint with custom React hooks/lint rules
- Zod or similar for form validation
- CSS (index.css) and possible CSS framework or custom styles

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer & Build Toolchain
    subgraph "Developer & Build Toolchain"
        Dev["Developer"]:::dev
        Git["Git"]:::dev
        ESLint["ESLint"]:::dev
        TS["TypeScript"]:::dev
        Vite["Vite (Dev Server & HMR)"]:::dev
        Build["Build Scripts"]:::dev
        CI["CI/CD Pipeline"]:::dev
        Dev -->|push| Git
        Git -->|triggers| CI
        CI -->|runs| Build
    end

    %% Frontend SPA
    subgraph "Frontend SPA"
        subgraph "Entry"
            Main["src/main.tsx"]:::frontend
            AppRoot["src/App.tsx"]:::frontend
            click Main "https://github.com/rgraffe/gema-frontend/blob/main/src/main.tsx"
            click AppRoot "https://github.com/rgraffe/gema-frontend/blob/main/src/App.tsx"
        end

        subgraph "Components"
            SidebarApp["AppSidebar.tsx"]:::frontend
            Sidebar["Sidebar.tsx"]:::frontend
            VerManual["VerManualDialog.tsx"]:::frontend
            EditUb["EditUbicacionForm.tsx"]:::frontend
            NewUb["FormNuevaUbicacion.tsx"]:::frontend
            NewTec["FormNuevoTecnico.tsx"]:::frontend
            GrpTrabajo["GruposTrabajo.tsx"]:::frontend
            UIPrims["UI Primitives\n(accordion, button, etc)"]:::frontend

            click SidebarApp "https://github.com/rgraffe/gema-frontend/blob/main/src/components/AppSidebar.tsx"
            click Sidebar "https://github.com/rgraffe/gema-frontend/blob/main/src/components/Sidebar.tsx"
            click VerManual "https://github.com/rgraffe/gema-frontend/blob/main/src/components/VerManualDialog.tsx"
            click EditUb "https://github.com/rgraffe/gema-frontend/blob/main/src/components/EditUbicacionForm.tsx"
            click NewUb "https://github.com/rgraffe/gema-frontend/blob/main/src/components/FormNuevaUbicacion.tsx"
            click NewTec "https://github.com/rgraffe/gema-frontend/blob/main/src/components/FormNuevoTecnico.tsx"
            click GrpTrabajo "https://github.com/rgraffe/gema-frontend/blob/main/src/components/GruposTrabajo.tsx"
            click UIPrims "https://github.com/rgraffe/gema-frontend/tree/main/src/components/ui/"
        end

        subgraph "Pages"
            Login["Login.tsx"]:::frontend
            Vista["VistaGeneral.tsx"]:::frontend
            Canva["Canva.tsx"]:::frontend
            Tecnicos["Tecnicos.tsx"]:::frontend
            Ubicaciones["UbicacionesTecnicas.tsx"]:::frontend

            click Login "https://github.com/rgraffe/gema-frontend/blob/main/src/pages/Login.tsx"
            click Vista "https://github.com/rgraffe/gema-frontend/blob/main/src/pages/VistaGeneral.tsx"
            click Canva "https://github.com/rgraffe/gema-frontend/blob/main/src/pages/Canva.tsx"
            click Tecnicos "https://github.com/rgraffe/gema-frontend/blob/main/src/pages/Tecnicos.tsx"
            click Ubicaciones "https://github.com/rgraffe/gema-frontend/blob/main/src/pages/UbicacionesTecnicas.tsx"
        end

        subgraph "Hooks & Validation & Types"
            Hook["use-mobile.ts"]:::frontend
            ValLogin["loginSchema.ts"]:::frontend
            ValGrp["grupoTrabajoSchema.ts"]:::frontend
            ValUb["ubicacionTecnicaSchema.ts"]:::frontend
            TypesUsr["usuarios.types.ts"]:::frontend
            TypesGrp["gruposTrabajo.types.ts"]:::frontend
            TypesTec["tecnicos.types.ts"]:::frontend
            TypesUb["ubicacionesTecnicas.types.ts"]:::frontend
            Utils["utils.ts"]:::frontend
            Styles["index.css"]:::frontend

            click Hook "https://github.com/rgraffe/gema-frontend/blob/main/src/hooks/use-mobile.ts"
            click ValLogin "https://github.com/rgraffe/gema-frontend/blob/main/src/validators/loginSchema.ts"
            click ValGrp "https://github.com/rgraffe/gema-frontend/blob/main/src/validators/grupoTrabajoSchema.ts"
            click ValUb "https://github.com/rgraffe/gema-frontend/blob/main/src/validators/ubicacionTecnicaSchema.ts"
            click TypesUsr "https://github.com/rgraffe/gema-frontend/blob/main/src/types/usuarios.types.ts"
            click TypesGrp "https://github.com/rgraffe/gema-frontend/blob/main/src/types/gruposTrabajo.types.ts"
            click TypesTec "https://github.com/rgraffe/gema-frontend/blob/main/src/types/tecnicos.types.ts"
            click TypesUb "https://github.com/rgraffe/gema-frontend/blob/main/src/types/ubicacionesTecnicas.types.ts"
            click Utils "https://github.com/rgraffe/gema-frontend/blob/main/src/lib/utils.ts"
            click Styles "https://github.com/rgraffe/gema-frontend/blob/main/src/index.css"
        end

        Main --> AppRoot
        AppRoot --> Components
        AppRoot --> Pages
        Pages --> Components
        Pages --> Hook
        Pages --> ValLogin
        Pages --> ValGrp
        Pages --> ValUb
        Components --> UIPrims
        Components --> Hook
    end

    %% Service Layer
    subgraph "Service Layer"
        AuthS["AuthService"]:::service
        GrpS["GruposDeTrabajoService"]:::service
        TecS["TecnicosService"]:::service
        UbS["UbicacionesTecnicasService"]:::service

        click AuthS "https://github.com/rgraffe/gema-frontend/blob/main/src/services/auth.ts"
        click GrpS "https://github.com/rgraffe/gema-frontend/blob/main/src/services/gruposDeTrabajo.ts"
        click TecS "https://github.com/rgraffe/gema-frontend/blob/main/src/services/tecnicos.ts"
        click UbS "https://github.com/rgraffe/gema-frontend/blob/main/src/services/ubicacionesTecnicas.ts"
    end

    %% Static Assets
    subgraph "Static Assets"
        HTML["index.html"]:::static
        PDF["guia-ubicaciones-tecnicas.pdf"]:::static

        click HTML "https://github.com/rgraffe/gema-frontend/blob/main/public/index.html"
        click PDF "https://github.com/rgraffe/gema-frontend/blob/main/public/guia-ubicaciones-tecnicas.pdf"
    end

    %% External Backend
    ExternalAPI["External Backend API"]:::external

    %% CDN Deployment
    CDN["CDN / Static Server"]:::static

    %% Browser
    Browser["Browser"]:::frontend

    %% Relationships
    Build -->|deploy| CDN
    CDN --> HTML
    CDN --> PDF
    Vite -->|serves| HTML
    Vite -->|serves| PDF
    Vite <--> Browser
    Browser -->|loads SPA| Main
    Browser -->|GET PDF| PDF
    Browser -->|calls| AuthS
    Browser -->|calls| GrpS
    Browser -->|calls| TecS
    Browser -->|calls| UbS
    AuthS -->|HTTP/JSON| ExternalAPI
    GrpS -->|HTTP/JSON| ExternalAPI
    TecS -->|HTTP/JSON| ExternalAPI
    UbS -->|HTTP/JSON| ExternalAPI

    %% Styles
    classDef dev fill:#D0E6FF,stroke:#0288D1,color:#000
    classDef frontend fill:#E8F5E9,stroke:#388E3C,color:#000
    classDef service fill:#FFF3E0,stroke:#FB8C00,color:#000
    classDef external fill:#FFEBEE,stroke:#E53935,color:#000
    classDef static fill:#F3E5F5,stroke:#8E24AA,color:#000
```
