# ofwirawan/verbose-garbonzo-tariff architecture

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

- Interactive diagram: https://gitdiagram.com/ofwirawan/verbose-garbonzo-tariff
- Repository: https://github.com/ofwirawan/verbose-garbonzo-tariff

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“verbose-garbonzo-tariff”) that provides a user interface for calculating and comparing tariff costs and uses a Java Spring Boot backend to handle business logic, data persistence, ML-driven recommendations, and external integrations.

##### Main Components
a. Frontend (Next.js)
- React UI pages under `frontend/app`, shared components in `frontend/components`, global styles and layout.
- Frontend logic calling both internal API routes (`frontend/app/api/*`) and Supabase for authentication (`frontend/lib/supabaseClient.ts`).
- Uses Prisma for local seeding (`frontend/prisma/schema.prisma`, `seed.ts`).
b. API Gateway (Next.js API Routes)
- Proxy routes (`[...proxy]/route.ts`) to forward certain calls to the Java backend.
- Auth routes (`/api/auth`), history, tariff lookup (`/api/wits-tariff`), etc.
c. Backend (Java Spring Boot “tariff” service)
- TariffApplication entry point.
- Controllers for public endpoints (tariff, AI, metadata, statistics, history, auth) and admin endpoints under `/controller/admin`.
- Service layer (`/service` packages) including ML model service (TariffMLService), AIRecommendationService, FreightService, GeminiSummaryService, and cache refresh.
- Repository layer (`/repository`) using Spring Data JPA for Country, Product, Suspension, Transaction, UserInfo, etc.
- Domain models (`/model`), DTOs, global exception handler, JWT filter for security, Swagger config.
d. Persistence Layer
- Relational database accessed by Spring Data JPA (configured via `application.properties` or `WebClientConfig`).
- Prisma schema in frontend for local dev but the production DB is managed by the backend.
e. External Services
- WITS tariff data via `WitsMetadataClient`.
- AI/ML recommendations via Gemini API or OpenAI endpoints (GeminiSummaryService).
- Supabase for authentication and user management (frontend).
f. DevOps/CI-CD
- GitHub Actions workflows for CI, security scans, Docker build & push, and deploy.
- Dockerfiles (`tariff/Dockerfile`, `frontend/Dockerfile` implicit in build scripts).
- Render.com deployment via `render.yaml`, `render-build.sh`, `run-prod.sh`, `run-local.sh`.

##### Relationships and Data Flows
- User’s browser → Next.js front end (React UI)
→ Next.js API routes (Auth, Proxy, History, WITS lookup)
→ Java Spring Boot service (REST controllers)
→ Service layer → Repository layer → Database
→ External WITS / AI services
- Authentication flow: Browser ↔ Supabase (via Next.js API/auth) ↔ JWT filter in backend
- Admin operations: Frontend admin pages → Next.js API proxy → Admin controllers in backend → Database

##### Architectural Patterns and Principles
- Layered architecture: UI → API Gateway → Controller → Service → Repository → DB
- MVC within backend (Controllers + Services + Repositories + Models)
- Single backend service (monolith) with clear module separation (admin vs public, AI vs tariff vs history)
- API gateway pattern at the Next.js layer to decouple frontend from backend host/ports
- Integration of external services via dedicated client classes (WitsMetadataClient, Gemini services)
- CI/CD pipeline to automate testing, containerization, and deployment to Render

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        UI["Next.js UI (TSX pages & components)"]:::frontend
    end

    %% API Gateway Layer
    subgraph "API Gateway Layer" 
        direction TB
        APIGW["Next.js API Routes (proxy & auth)"]:::api
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        SBApp["Spring Boot Tariff Service"]:::backend
        subgraph "Controllers"
            direction TB
            PubCtrl["Public Controllers"]:::backend
            AdminCtrl["Admin Controllers"]:::backend
        end
        subgraph "Services"
            direction TB
            ServiceLayer["Service Layer (Business Logic & ML)"]:::backend
        end
        subgraph "Repositories"
            direction TB
            RepoLayer["Repository Layer (JPA Repos)"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["PostgreSQL (JPA Entities)"]:::db
        Prisma["Prisma Schema & Seed (Local Dev)"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        WITS["WITS External API"]:::ext
        AIAPI["OpenAI/Gemini API"]:::ext
        Supabase["Supabase Auth"]:::ext
    end

    %% DevOps / CI-CD
    subgraph "DevOps / CI-CD"
        direction TB
        CICD["GitHub Actions → Docker → Render"]:::devops
    end

    %% Connections
    UI -->|"GET/POST"| APIGW
    APIGW -->|"REST Calls"| SBApp
    SBApp --> ServiceLayer
    ServiceLayer --> RepoLayer
    RepoLayer --> DB
    ServiceLayer --> WITS
    ServiceLayer --> AIAPI
    UI -->|"Auth Tokens"| Supabase
    Supabase -->|"JWT"| SBApp
    CICD -.-> SBApp
    CICD -.-> UI

    %% Click Events
    click UI "https://github.com/ofwirawan/verbose-garbonzo-tariff/tree/main/frontend/app"
    click UI "https://github.com/ofwirawan/verbose-garbonzo-tariff/tree/main/frontend/components"
    click APIGW "https://github.com/ofwirawan/verbose-garbonzo-tariff/tree/main/frontend/app/api"
    click APIGW "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/frontend/app/api/[...proxy]/route.ts"
    click APIGW "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/frontend/app/api/auth/route.ts"
    click APIGW "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/frontend/app/api/history/route.ts"
    click APIGW "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/frontend/app/api/wits-tariff/route.ts"
    click PubCtrl "https://github.com/ofwirawan/verbose-garbonzo-tariff/tree/main/tariff/src/main/java/com/verbosegarbonzo/tariff/controller"
    click AdminCtrl "https://github.com/ofwirawan/verbose-garbonzo-tariff/tree/main/tariff/src/main/java/com/verbosegarbonzo/tariff/controller/admin"
    click ServiceLayer "https://github.com/ofwirawan/verbose-garbonzo-tariff/tree/main/tariff/src/main/java/com/verbosegarbonzo/tariff/service"
    click RepoLayer "https://github.com/ofwirawan/verbose-garbonzo-tariff/tree/main/tariff/src/main/java/com/verbosegarbonzo/tariff/repository"
    click SBApp "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/tariff/src/main/java/com/verbosegarbonzo/tariff/TariffApplication.java"
    click WITS "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/tariff/src/main/java/com/verbosegarbonzo/tariff/client/WitsMetadataClient.java"
    click AIAPI "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/tariff/src/main/java/com/verbosegarbonzo/tariff/service/GeminiSummaryService.java"
    click Supabase "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/frontend/lib/supabaseClient.ts"
    click Prisma "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/frontend/prisma/schema.prisma"
    click Prisma "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/frontend/prisma/seed.ts"
    click CICD "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/.github/workflows/ci.yml"
    click CICD "https://github.com/ofwirawan/verbose-garbonzo-tariff/blob/main/.github/workflows/deploy.yml"
    click CICD "https://github.com/ofwirawan/verbose-garbonzo-tariff/tree/main/tariff/Dockerfile"
    click CICD "https://github.com/ofwirawan/verbose-garbonzo-tariff/tree/main/frontend/Dockerfile"

    %% Styles
    classDef frontend fill:#CEF,stroke:#036,stroke-width:1px
    classDef api fill:#CFC,stroke:#090,stroke-width:1px
    classDef backend fill:#FED,stroke:#F80,stroke-width:1px
    classDef db fill:#EEE,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
    classDef ext fill:#DDF,stroke:#55F,stroke-width:1px
    classDef devops fill:#FFD,stroke:#DA0,stroke-width:1px
```
