# digitales-2025/admin-viesglo architecture

> Architecture diagram of the GitHub repository digitales-2025/admin-viesglo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/digitales-2025/admin-viesglo
- Repository: https://github.com/digitales-2025/admin-viesglo

## Overview

##### Project Type and Purpose
- This is a full-stack administrative panel (MSM Consulting – Sistema de Gestión de Proyectos) built on Next.js (App Router), Tailwind, Shadcn/UI, TanStack Query/Table.
- It provides CRUD interfaces for clients, clinics, projects, certificates, medical records, user/role management, real-time MQTT features, reporting and analytics.
- There is also a DevOps subfolder with Jenkins pipelines, Dockerfiles, Ansible playbooks and Vault templates—so the repo contains both application code and infrastructure-as-code.

##### File Structure
- Top-level “src/app” holds the Next.js App Router pages and layouts, organized by route (auth, dashboard/admin, public).
- “src/shared” contains a component library (UI primitives, mqtt wrappers, hooks, services, stores, data schemas) shared across the app.
- “src/lib” provides low-level HTTP clients and type definitions for backend API contracts.
- “devops/” and “deploy/” contain CI/CD pipelines (Jenkinsfiles, Groovy scripts), Dockerfiles for dev/prod, Docker-Compose templates, Ansible playbooks for provisioning and service rollout, and Vault YAMLs for secret management.
- Configuration files at root: pnpm-lock.json, next.config.ts, tsconfig.json, lint/prettier, Git hooks.

##### README for Additional Insights
- Confirms stack: Node.js 18+, pnpm, Next.js 15, Tailwind v4, Shadcn, TanStack Query/Table.
- Mentions requirement of a database (MongoDB/PostgreSQL) and environment variables.

##### Main Components & Their Interactions
a. Browser (React client):
- Renders pages from Next.js, uses TanStack Query to call APIs and WebSocket/MQTT for real-time.
b. Next.js Server (Node.js):
- SSR/SSG of React pages, API routes or proxy to backend services, hosts static assets.
c. Backend API Service (separate microservice or next built-in API):
- Exposes REST/GraphQL endpoints for CRUD operations, implements business logic, communicates with database.
d. Database(s):
- MongoDB or PostgreSQL for persistent storage of projects, users, certificates, medical records.
e. MQTT Broker:
- Provides pub/sub real-time channels for notifications and live data (uses shared/mqtt wrappers).
f. CI/CD Pipeline & Infrastructure:
- Jenkins orchestrates build/test/deploy pipelines.
- Docker/Docker-Compose builds container images of the app.
- Ansible playbooks provision servers/containers and configure services.
- Vault for secret management.

##### Architectural Patterns & Design Principles
- Layered architecture: Presentation (Next.js pages) → Application (hooks/services/controllers) → Data (API clients, database).
- Component-based UI with Shadcn primitives and a shared component library.
- TanStack Query for data fetching/caching, promoting separation of concerns.
- MQTT integration via context providers and hooks—decouple real-time flows from business logic.
- Infrastructure-as-Code: Jenkinsfiles, Ansible, Dockerfiles, Vault.

##### Elements
- Components with clear labels: Browser, Next.js App, API Service, Database, MQTT Broker, Jenkins, Vault, Ansible, Docker Registry.
- Browser → Next.js (HTTP/SSR)
- Browser ↔ MQTT Broker (WebSocket/MQTT)
- Next.js → Backend API (REST/GraphQL)
- Backend API → Database (SQL/NoSQL)
- Jenkins → Docker Registry → Deployment Servers
- Ansible → Hosts for configuration
- Vault → Jenkins/Ansible for secret retrieval
- User-facing components (blue)
- Internal services (green)
- Infrastructure/DevOps (gray)
- Data stores (orange)

##### Putting It All Together
- Underneath, illustrate the DevOps pipeline: Jenkins pulling code, building Docker images, pushing to registry, Ansible deploying to servers, Vault providing secrets.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Browser (React Client)"]:::frontend
        NextApp["Next.js Server"]:::frontend
        subgraph "App Router Pages"
            direction TB
            Auth["Public Auth Module"]:::frontend
            Dashboard["Dashboard/Admin Interface"]:::frontend
        end
    end

    %% Shared Library
    subgraph "Shared Library & Hooks"
        direction TB
        UIPrims["UI Primitives & Layouts"]:::frontend
        subgraph "MQTT Library"
            direction TB
            MQTTComp["MQTT Components"]:::frontend
            MQTTProvider["MQTT Provider"]:::frontend
            MQTTConfig["MQTT Config"]:::frontend
            UseMQTT["use-mqtt Hook"]:::frontend
            UseMQTTPub["use-mqtt-publish Hook"]:::frontend
            MQTTActions["mqtt.actions"]:::frontend
            MQTTActionsSrv["mqtt-server.actions"]:::frontend
        end
        QueryProvider["Query Provider"]:::frontend
        APItypes["API Types"]:::frontend
        BackendTypes["Backend Types"]:::frontend
        CommonTypes["Common Types"]:::frontend
        HTTPClientFetch["clientFetch HTTP Client"]:::frontend
        HTTPServerFetch["serverFetch HTTP Client"]:::frontend
        Utils["Utilities"]:::frontend
        Stores["Zustand Stores"]:::frontend
    end

    %% Backend Services and Data
    subgraph "Backend & Data"
        direction TB
        APIService["Backend API Service"]:::service
        MQTTBroker["MQTT Broker"]:::service
        Database["Database (MongoDB/PostgreSQL)"]:::data
    end

    %% DevOps Infrastructure
    subgraph "DevOps Infrastructure"
        direction TB
        Jenkins["Jenkins CI/CD"]:::infra
        DockerRegistry["Docker Registry"]:::infra
        Ansible["Ansible Playbooks"]:::infra
        Vault["Vault Secret Management"]:::infra
        Deployment["Deployment Servers"]:::infra
    end

    %% Connections
    Browser -->|"HTTP/SSR"| NextApp
    Browser <-->|"MQTT/WebSocket"| MQTTBroker
    NextApp -->|"REST/GraphQL"| APIService
    NextApp -->|"MQTT"| MQTTBroker
    APIService -->|"SQL/NoSQL"| Database

    Jenkins --> DockerRegistry
    DockerRegistry --> Deployment
    Ansible --> Deployment
    Vault --> Jenkins
    Vault --> Ansible

    %% Click Events - Frontend
    click Browser "https://github.com/digitales-2025/admin-viesglo/tree/develop/src/app"
    click NextApp "https://github.com/digitales-2025/admin-viesglo/blob/develop/next.config.ts"
    click Auth "https://github.com/digitales-2025/admin-viesglo/tree/develop/src/app/(public)/auth"
    click Dashboard "https://github.com/digitales-2025/admin-viesglo/tree/develop/src/app/dashboard/admin"
    click UIPrims "https://github.com/digitales-2025/admin-viesglo/tree/develop/src/shared/components"
    click MQTTComp "https://github.com/digitales-2025/admin-viesglo/tree/develop/src/shared/components/mqtt"
    click MQTTProvider "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/shared/context/mqtt-provider.tsx"
    click MQTTConfig "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/shared/config/mqtt.config.ts"
    click UseMQTT "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/shared/hooks/use-mqtt.ts"
    click UseMQTTPub "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/shared/hooks/use-mqtt-publish.ts"
    click MQTTActions "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/shared/actions/mqtt.actions.ts"
    click MQTTActionsSrv "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/shared/actions/mqtt-server.actions.ts"
    click QueryProvider "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/shared/context/query-provider.tsx"
    click APItypes "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/lib/api/types/api.ts"
    click BackendTypes "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/lib/api/types/backend.ts"
    click CommonTypes "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/lib/api/types/common.ts"
    click HTTPClientFetch "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/lib/http/clientFetch.ts"
    click HTTPServerFetch "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/lib/http/serverFetch.ts"
    click Utils "https://github.com/digitales-2025/admin-viesglo/blob/develop/src/lib/utils.ts"
    click Stores "https://github.com/digitales-2025/admin-viesglo/tree/develop/src/shared/stores"

    %% Click Events - DevOps
    click Jenkins "https://github.com/digitales-2025/admin-viesglo/tree/develop/devops/+ci/Jenkinsfile"
    click DockerRegistry "https://github.com/digitales-2025/admin-viesglo/tree/develop/devops/docker/Dockerfile"
    click Ansible "https://github.com/digitales-2025/admin-viesglo/blob/develop/devops/ansible/service_pull_and_setup.yml"
    click Vault "https://github.com/digitales-2025/admin-viesglo/blob/develop/devops/+develop/vault.yml"
    click Deployment "https://github.com/digitales-2025/admin-viesglo/blob/develop/deploy/Jenkins.dev.groovy"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef service fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef data fill:#ffe5b4,stroke:#333,stroke-width:1px;
    classDef infra fill:#e2e3e5,stroke:#333,stroke-width:1px;
```
