How ofwirawan/verbose-garbonzo-tariff works
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