# darexl/veronica-open-api architecture

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

- Interactive diagram: https://gitdiagram.com/darexl/veronica-open-api
- Repository: https://github.com/darexl/veronica-open-api

## Overview

##### Project Type & Purpose
- Veronica is a full-stack backend API (Spring-Boot 1.5.9) for electronic invoicing under Ecuador’s SRI rules.
- It persists documents in PostgreSQL, signs XML, generates PDF RIDEs, secures endpoints via OAuth2, and publishes Swagger docs.

##### Core Architectural Layers & Modules
A top-level view splits the system into these modules (Maven sub-projects):
- **app**
- Spring-Boot entrypoint (VeronicaApplication)
- REST Controllers (app/api/v1)
- Configuration (Security, Swagger, JAXB, Beans)
- OAuth2 Authorization & Resource Server
- **service**
- Business logic layer
- Service interfaces & implementations for CRUD and SRI operations
- XML signer, digital certificate handling (MITyC, xmlsec, jss libs)
- **persistence**
- Spring Data JPA repositories (CRUD on domain entities)
- **domain**
- JPA Entity definitions (Invoice, CreditMemo, DebitMemo, etc.)
- **ride**
- RIDEGenerator producing PDFs via JasperReports JRXML templates
- **additional_libs**
- Custom jars (MITyC Java signing, xmlsec, jss) installed manually into Maven local

##### External Dependencies & Services
- **Database**: PostgreSQL
- **SRI Web Service**: External REST/SOAP endpoints for document authorization
- **OAuth2 Clients**: Clients obtain Bearer tokens from Veronica’s /oauth/token
- **Swagger UI**: Built into app at /swagger-ui.html
- **Postman Collection**: Examples under src/postman

##### Relationships & Data Flow
- **Client** → (HTTPS/JSON+Bearer) → **app:Controller**
- **Controller** → **service:BusinessLogic**
- CRUD services call **persistence:Repository** → **PostgreSQL**
- SRI services call external **SRI Web Service**
- Digital signature routines use **additional_libs**
- **service** → **ride:RIDEGenerator** to produce PDF
- **Controller** returns status, signed XML, PDF links

##### Architectural Patterns & Design Principles
- **Layered Architecture**: Presentation (Controllers), Service, Persistence, Domain
- **Dependency Injection** via Spring
- **API Versioning** under /api/v1.0
- **OAuth2** for security (Authorization Server + Resource Server)
- **Externalization of Config**: application.properties, filters (dev/prd), log4j2

##### Essential Elements
- External service: SRI
- Blue = API/Controllers
- Green = Business Services
- Yellow = Persistence/DB
- Gray = External libs & services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs for layers/modules
    subgraph "API Layer (app)" 
        direction TB
        VeronicaApplication["VeronicaApplication"]:::frontend
        Controllers["REST Controllers (api/v1)"]:::frontend
        OperationController["OperationController"]:::frontend
        Config["Configuration"]:::frontend
        SwaggerConfig["SwaggerConfig"]:::frontend
        OAuth2Config["OAuth2 (Auth & Resource Server)"]:::frontend
    end

    subgraph "Service Layer (service)"
        direction TB
        ServiceCore["Service Interfaces & Impl"]:::backend
        CommonUtils["XML Signing Utilities"]:::backend
        CrudServices["CRUD Services"]:::backend
        SriServices["SRI Services v1"]:::backend
    end

    subgraph "Persistence Layer (persistence)"
        direction TB
        Repositories["JPA Repositories"]:::persistence
    end

    subgraph "Domain Layer (domain)"
        direction TB
        Entities["JPA Entities"]:::persistence
        XMLType["XMLType"]:::persistence
    end

    subgraph "RIDE Module (ride)"
        direction TB
        RIDEGenerator["RIDEGenerator"]:::backend
        JRXMLTemplates["JRXML Templates"]:::backend
    end

    subgraph "Additional Libs"
        direction TB
        AdditionalLibs["Signing JARs"]:::external
    end

    subgraph "External Services & DB"
        direction TB
        PostgreSQL["PostgreSQL"]:::external
        SRIService["SRI Web Service"]:::external
    end

    %% Client
    Client["Client"]:::external

    %% Data Flow
    Client -->|"HTTPS/JSON + Bearer"| Controllers
    Controllers -->|calls| ServiceCore
    Controllers -->|calls| CrudServices
    ServiceCore -->|uses| Repositories
    CrudServices -->|CRUD ops| Repositories
    Repositories -->|reads/writes| PostgreSQL
    ServiceCore -->|calls| SriServices
    SriServices -->|REST/SOAP| SRIService
    ServiceCore -->|uses| CommonUtils
    CommonUtils -->|signs XML| AdditionalLibs
    ServiceCore -->|generates PDF| RIDEGenerator
    RIDEGenerator -->|templates| JRXMLTemplates
    Controllers -->|returns| SwaggerConfig

    %% Click Events
    click VeronicaApplication "https://github.com/darexl/veronica-open-api/blob/master/app/src/main/java/com/rolandopalermo/facturacion/ec/app/VeronicaApplication.java"
    click Controllers "https://github.com/darexl/veronica-open-api/tree/master/app/src/main/java/com/rolandopalermo/facturacion/ec/app/api/v1/"
    click OperationController "https://github.com/darexl/veronica-open-api/blob/master/app/src/main/java/com/rolandopalermo/facturacion/ec/app/api/OperationController.java"
    click Config "https://github.com/darexl/veronica-open-api/tree/master/app/src/main/java/com/rolandopalermo/facturacion/ec/app/config/"
    click SwaggerConfig "https://github.com/darexl/veronica-open-api/blob/master/app/src/main/java/com/rolandopalermo/facturacion/ec/app/config/SwaggerConfig.java"
    click OAuth2Config "https://github.com/darexl/veronica-open-api/tree/master/app/src/main/java/com/rolandopalermo/facturacion/ec/app/oauth2/"
    click ServiceCore "https://github.com/darexl/veronica-open-api/tree/master/service/src/main/java/com/rolandopalermo/facturacion/ec/service/"
    click CommonUtils "https://github.com/darexl/veronica-open-api/tree/master/service/src/main/java/com/rolandopalermo/facturacion/ec/service/common/"
    click CrudServices "https://github.com/darexl/veronica-open-api/tree/master/service/src/main/java/com/rolandopalermo/facturacion/ec/service/crud/"
    click SriServices "https://github.com/darexl/veronica-open-api/tree/master/service/src/main/java/com/rolandopalermo/facturacion/ec/service/sri/v1/"
    click Repositories "https://github.com/darexl/veronica-open-api/tree/master/persistence/src/main/java/com/rolandopalermo/facturacion/ec/persistence/"
    click Entities "https://github.com/darexl/veronica-open-api/tree/master/domain/src/main/java/com/rolandopalermo/facturacion/ec/domain/"
    click XMLType "https://github.com/darexl/veronica-open-api/blob/master/domain/src/main/java/com/rolandopalermo/facturacion/ec/domain/type/XMLType.java"
    click RIDEGenerator "https://github.com/darexl/veronica-open-api/blob/master/ride/src/main/java/com/rolandopalermo/facturacion/ec/ride/RIDEGenerator.java"
    click JRXMLTemplates "https://github.com/darexl/veronica-open-api/tree/master/ride/src/main/resources/com/rolandopalermo/facturacion/ec/ride/"
    click AdditionalLibs "https://github.com/darexl/veronica-open-api/tree/master/additional_libs/"
    click PostgreSQL "https://github.com/darexl/veronica-open-api/blob/master/src/sql/veronica.sql"
    click SRIService "https://github.com/darexl/veronica-open-api/blob/master/src/postman/Verónica API Reference.postman_collection.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#e0ffd8,stroke:#28a745,color:#28a745;
    classDef persistence fill:#fff5b1,stroke:#dbab09,color:#dbab09;
    classDef external fill:#f0f0f0,stroke:#6a737d,color:#6a737d;
```
