# jhousefsilva1/st_ms_persons architecture

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

- Interactive diagram: https://gitdiagram.com/jhousefsilva1/st_ms_persons
- Repository: https://github.com/jhousefsilva1/st_ms_persons

## Overview

##### Project type and purpose
- This is a Spring-Boot-based, monolithic backend microservice named SmartTolls_PersonsService.
- Its responsibilities are:
- User authentication/authorization (JWT-based)
- CRUD operations for Persons, PersonTypes, and Genders
- Integration with an external Country-City lookup service

##### File structure
- src/main/java/com/smart/tolls/…/Auth: all classes related to security (controllers, filters, JWT logic, token repository).
- src/main/java/com/smart/tolls/…/Controller: REST endpoints for domain resources.
- src/main/java/com/smart/tolls/…/Service: business logic.
- src/main/java/com/smart/tolls/…/Repository: Spring Data JPA interfaces.
- src/main/java/com/smart/tolls/…/Entity & Dto: persistence models vs. data-transfer objects
- src/main/java/com/smart/tolls/…/Client: CountryCityClient for external API calls
- src/main/resources/application.yml: configuration (DB, JWT secrets, external-service URL)

##### Key architectural patterns
- Layered (Controller → Service → Repository → Database)
- Spring Security filter chain with JwtAuthenticationFilter
- External API integration via a typed HTTP client
- Separation of concerns: Auth module vs. Domain module

##### Main components & relationships
[External User or System]
│ (1) HTTP(S) Request
▼
[JwtAuthenticationFilter] ── if authenticated ──►
│
▼
[Controller Layer]
- AuthController
- StPersonController
- StGenderController
- StPersonTypeController
│
▼
[Service Layer]
- AuthService & JwtService
- StPersonService
- StGenderService
- StPersonTypeService
│
├─ calls ──► [Repository Layer]
│              • StPersonRepository
│              • StGenderRepository
│              • StPersonTypeRepository
│              • TokenRepository
│
└─ invokes ──► [CountryCityClient] ──► [External Country/City API]
│
▼
[Database] (e.g., PostgreSQL, MySQL)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User/System
    User(("User\n/System")):::external

    %% API & Security Layer
    subgraph "API & Security Layer"
        direction TB
        JwtFilter["JwtAuthenticationFilter"]:::api
        AuthController["AuthController"]:::api
        ApiController["ApiController"]:::api
        PersonController["StPersonController"]:::api
        GenderController["StGenderController"]:::api
        PersonTypeController["StPersonTypeController"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        AuthService["AuthService"]:::service
        JwtService["JwtService"]:::service
        PersonService["StPersonService"]:::service
        GenderService["StGenderService"]:::service
        PersonTypeService["StPersonTypeService"]:::service
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        PersonRepo["StPersonRepository"]:::repo
        GenderRepo["StGenderRepository"]:::repo
        PersonTypeRepo["StPersonTypeRepository"]:::repo
        TokenRepo["TokenRepository"]:::repo
    end

    %% External dependencies
    subgraph "External Systems"
        direction TB
        CountryCityAPI(("Country/City API")):::external
    end

    CountryCityClient["CountryCityClient"]:::service

    %% Database
    Database[(Database)]:::database

    %% Configuration
    Config(["application.yml\n(DB, JWT, External API)"]):::repo

    %% Flows
    User -->|HTTPS Request| JwtFilter
    JwtFilter -->|forward if JWT valid| AuthController
    JwtFilter -->|forward if JWT valid| ApiController
    JwtFilter -->|forward if JWT valid| PersonController
    JwtFilter -->|forward if JWT valid| GenderController
    JwtFilter -->|forward if JWT valid| PersonTypeController

    AuthController -->|"calls"| AuthService
    AuthController -->|"calls"| JwtService

    ApiController -->|"calls"| AuthService

    PersonController -->|"calls"| PersonService
    GenderController -->|"calls"| GenderService
    PersonTypeController -->|"calls"| PersonTypeService

    AuthService -->|"uses"| TokenRepo
    AuthService -->|"generates/validates JWT"| JwtService

    PersonService -->|"CRUD"| PersonRepo
    GenderService -->|"CRUD"| GenderRepo
    PersonTypeService -->|"CRUD"| PersonTypeRepo

    PersonService -->|"calls"| CountryCityClient
    CountryCityClient -->|HTTP Request| CountryCityAPI

    PersonRepo -->|reads/writes| Database
    GenderRepo -->|reads/writes| Database
    PersonTypeRepo -->|reads/writes| Database
    TokenRepo -->|reads/writes| Database

    Config -->|provides settings| JwtFilter
    Config -->|provides settings| CountryCityClient
    Config -->|provides settings| Database

    %% Click Events
    click JwtFilter "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Auth/JwtAuthenticationFilter.java"
    click AuthController "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Auth/AuthController.java"
    click AuthService "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Auth/AuthService.java"
    click JwtService "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Auth/JwtService.java"
    click TokenRepo "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Auth/TokenRepository.java"
    click PersonController "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Controller/StPersonController.java"
    click GenderController "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Controller/StGenderController.java"
    click PersonTypeController "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Controller/StPersonTypeController.java"
    click ApiController "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Controller/ApiController.java"
    click PersonService "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Service/StPersonService.java"
    click GenderService "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Service/StGenderService.java"
    click PersonTypeService "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Service/StPersonTypeService.java"
    click PersonRepo "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Repository/StPersonRepository.java"
    click GenderRepo "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Repository/StGenderRepository.java"
    click PersonTypeRepo "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Repository/StPersonTypeRepository.java"
    click CountryCityClient "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/java/com/smart/tolls/ucb/edu/bo/SmartTolls_PersonsService/Client/CountryCityClient.java"
    click Config "https://github.com/jhousefsilva1/st_ms_persons/blob/main/src/main/resources/application.yml"

    %% Styles
    classDef api fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef service fill:#d4edda,stroke:#333,stroke-width:1px
    classDef repo fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef external fill:#d6d6d6,stroke:#333,stroke-width:1px
    classDef database fill:#a9a9a9,stroke:#333,stroke-width:1px
```
