# henriquegsena/cep-manager architecture

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

- Interactive diagram: https://gitdiagram.com/henriquegsena/cep-manager
- Repository: https://github.com/henriquegsena/cep-manager

## Overview

##### Project type and purpose
- This is a full-stack web application for CEP lookup and address/user management.
- Frontend: React + Tailwind/shadCN + react-query + axios.
- Backend: Spring Boot (REST API) + WebFlux (for external HTTP client) + JPA + Liquibase + PostgreSQL.
- External service: ViaCEP API for address lookup.

##### File structure
- Top level:
- cepManagerServer/ – Java backend
- web-app/ – React frontend
- Backend sub-structure follows typical Spring Boot conventions:
- config/ – CORS, Swagger, WebClient (ViaCEP)
- controller/ – REST endpoints (CepController, UsuarioController)
- service/ – business logic (CepService, UsuariosService)
- repository/ – JPA repositories (UsuariosRepository)
- entities/, dto/, exceptions/
- resources/ – application.yml, Liquibase changelogs, Docker Compose for Postgres
- Frontend sub-structure:
- src/components – UI layout (DataTable, RegisterDialog, SearchBar) + primitives (button, dialog, input, label, pagination, table)
- src/hooks – React Query hooks for CRUD and ViaCEP lookup
- src/lib – API client (axios) and utilities
- Vite config + TypeScript setup

##### README for additional insights
- Describes CRUD operations, integration with ViaCEP, database persistence, Swagger UI for API docs, Docker Compose.
- Technology stack: React, shadCN, react-query, axios; Spring Boot, Liquibase, PostgreSQL.

a. Main components
– Browser/Client (React app)
– API Gateway (Spring Boot REST controllers)
– Business Services (CepService, UsuariosService)
– Persistence Layer (JPA → PostgreSQL)
– External Service (ViaCEP HTTP API)
– DevOps/infra: Docker Compose for Postgres, Swagger UI

b. Relationships and interactions
1. User interacts with React UI → form input triggers react-query hooks → axios HTTP calls to Spring Boot.
2. Spring Boot controllers route requests to service layer.
3. CepService calls ViaCEP via WebClient (configured in WebClientConfig).
4. UsersService interacts with UsuariosRepository (Spring Data JPA) → PostgreSQL.
5. Liquibase changelogs manage DB schema on startup.
6. Swagger UI auto-generates API docs on /swagger-ui/index.html.
7. Docker Compose spins up Postgres container for local development.

c. Architectural patterns and design principles
– Layered architecture (Controller → Service → Repository)
– DTOs for payload mapping
– Exception handling via GlobalExceptionHandler
– Configuration-driven (application.yml profiles)
– External integration via reactive WebClient
– Client-side caching and mutations via React Query

d. Key technologies/frameworks
– Frontend: React, TypeScript, Vite, shadCN/Tailwind, React Query, Axios
– Backend: Spring Boot Web MVC + WebFlux, Spring Data JPA, Lombok, Liquibase, PostgreSQL, Swagger (springdoc)
– Infra: Docker Compose, Maven wrapper

##### Final advice
- Be detailed but avoid clutter: represent each logical layer/component.
- Document environment setups (e.g., Docker Compose for Postgres) as side notes or infra layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        ReactApp["Browser / React App"]:::frontend
        subgraph "React Components" 
            direction TB
            DataTable["DataTable"]:::frontend
            RegisterDialog["RegisterDialog"]:::frontend
            SearchBar["SearchBar"]:::frontend
        end
        UIPrimitives["UI Primitives<br/>(shadCN/Tailwind)"]:::frontend
        subgraph "React Query Hooks & ViaCEP Lookup"
            direction TB
            CreateUser["useCreateUserMutate"]:::frontend
            DeleteUser["useDeleteUserMutate"]:::frontend
            UpdateUser["useUpdateUserMutate"]:::frontend
            FindAddress["useFindAddress"]:::frontend
        end
        subgraph "API Client & React Query"
            direction TB
            APIClient["Axios API Client"]:::frontend
            ReactQueryConfig["React Query Config"]:::frontend
        end
        subgraph "Utilities & Types"
            direction TB
            Utils["utils.ts"]:::frontend
            Types["DataTableProps, SearchBarProps, Usuarios.ts"]:::frontend
        end
        subgraph "Vite & TS Config"
            direction TB
            ViteConfig["vite.config.ts"]:::frontend
            TSConfig["tsconfig*.json"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        SpringApp["Spring Boot Application"]:::backend
        subgraph "Configuration Layer"
            direction TB
            CorsConfig["CorsConfig"]:::backend
            SwaggerConfig["SwaggerConfig"]:::backend
            WebClientConfig["WebClientConfig"]:::backend
        end
        subgraph "REST Controllers"
            direction TB
            CepController["CepController"]:::backend
            UsuarioController["UsuarioController"]:::backend
        end
        subgraph "Service Layer"
            direction TB
            CepService["CepService"]:::backend
            UsuariosService["UsuariosService"]:::backend
        end
        subgraph "Persistence Layer"
            direction TB
            UsuariosRepo["UsuariosRepository"]:::backend
        end
        subgraph "Entities & DTOs"
            direction TB
            EntityUsuarios["Usuarios Entity"]:::backend
            DTOS["CepDTO, UsuariosDTO"]:::backend
        end
        subgraph "Exception Handling"
            direction TB
            NotFoundEx["CeptNotFoundException"]:::backend
            GlobalHandler["GlobalExceptionHandler"]:::backend
        end
        subgraph "Application Config & Liquibase"
            direction TB
            AppYml["application.yml / application-dev.yml"]:::backend
            LiquibaseChg["Liquibase master & changelogs"]:::backend
        end
        SwaggerUI["Swagger UI"]:::external
        DockerCompose["Docker Compose Postgres"]:::infra
    end

    %% External & Infrastructure
    ExternalViaCEP["External Service<br/>ViaCEP API"]:::external
    PostgreSQL["PostgreSQL DB"]:::database

    %% Connections
    ReactApp -->|uses| DataTable
    ReactApp -->|uses| RegisterDialog
    ReactApp -->|uses| SearchBar
    DataTable -->|primitives| UIPrimitives
    RegisterDialog -->|primitives| UIPrimitives
    SearchBar -->|primitives| UIPrimitives
    DataTable -->|hooks| CreateUser
    SearchBar -->|hooks| FindAddress
    CreateUser -->|calls| APIClient
    DeleteUser -->|calls| APIClient
    UpdateUser -->|calls| APIClient
    FindAddress -->|calls| APIClient
    APIClient -->|HTTP calls| CepController
    APIClient -->|HTTP calls| UsuarioController
    SpringApp -->|bootstraps| CorsConfig
    SpringApp -->|bootstraps| SwaggerConfig
    SpringApp -->|bootstraps| WebClientConfig
    CepController -->|invokes| CepService
    UsuarioController -->|invokes| UsuariosService
    CepService -->|calls| ExternalViaCEP
    UsuariosService -->|uses| UsuariosRepo
    UsuariosRepo -->|connects to| PostgreSQL
    LiquibaseChg -->|manages schema| PostgreSQL
    AppYml -->|configures| SpringApp
    SwaggerConfig -->|exposes| SwaggerUI
    DockerCompose -->|runs| PostgreSQL

    %% Click Events
    click ReactApp "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/main.tsx"
    click DataTable "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/components/layout/DataTable.tsx"
    click RegisterDialog "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/components/layout/RegisterDialog.tsx"
    click SearchBar "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/components/layout/SearchBar.tsx"
    click UIPrimitives "https://github.com/henriquegsena/cep-manager/tree/main/web-app/src/components/ui/"
    click CreateUser "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/hooks/useCreateUserMutate.ts"
    click DeleteUser "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/hooks/useDeleteUserMutate.ts"
    click UpdateUser "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/hooks/useUpdateUserMutate.ts"
    click FindAddress "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/hooks/useFindAddress.ts"
    click APIClient "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/service/api.ts"
    click ReactQueryConfig "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/lib/react-query.ts"
    click Utils "https://github.com/henriquegsena/cep-manager/blob/main/web-app/src/lib/utils.ts"
    click Types "https://github.com/henriquegsena/cep-manager/tree/main/web-app/src/utlis/"
    click ViteConfig "https://github.com/henriquegsena/cep-manager/blob/main/web-app/vite.config.ts"
    click TSConfig "https://github.com/henriquegsena/cep-manager/blob/main/web-app/tsconfig.json"
    click SpringApp "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/CepManagerApplication.java"
    click CorsConfig "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/config/CorsConfig.java"
    click SwaggerConfig "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/config/SwaggerConfig.java"
    click WebClientConfig "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/config/WebClientConfig.java"
    click CepController "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/controller/CepController.java"
    click UsuarioController "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/controller/UsuarioController.java"
    click CepService "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/service/CepService.java"
    click UsuariosService "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/service/UsuariosService.java"
    click UsuariosRepo "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/repository/UsuariosRepository.java"
    click EntityUsuarios "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/entities/Usuarios.java"
    click DTOS "https://github.com/henriquegsena/cep-manager/tree/main/cepManagerServer/src/main/java/com/br/cepManager/dto/"
    click NotFoundEx "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/exceptions/CeptNotFoundException.java"
    click GlobalHandler "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/java/com/br/cepManager/exceptions/GlobalExceptionHandler.java"
    click AppYml "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/resources/application.yml"
    click LiquibaseChg "https://github.com/henriquegsena/cep-manager/tree/main/cepManagerServer/src/main/resources/config/liquibase/"
    click DockerCompose "https://github.com/henriquegsena/cep-manager/blob/main/cepManagerServer/src/main/docker/postgres.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#DFFFE0,stroke:#028a0f,color:#028a0f;
    classDef external stroke-dasharray: 5 5,fill:#FFF,stroke:#d87600,color:#d87600;
    classDef database fill:#FFF0B3,stroke:#B38500,color:#B38500;
    classDef infra fill:#EFEFEF,stroke:#666666,color:#666666;
```
