# adriantd3/shoppinglist architecture

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

- Interactive diagram: https://gitdiagram.com/adriantd3/shoppinglist
- Repository: https://github.com/adriantd3/shoppinglist

## Overview

##### Project type and purpose
- This is a full-stack “shopping list” application with:
- A Next.js / React Native-style frontend (“Dutylist”)
- A central Spring Boot monolith (ShoppingListApplication) handling auth, lists, items
- Two supporting Spring Boot microservices (Products & Users) generated via OpenAPI
- A relational database for persistence (db_structure.sql, db_data.sql)
- External identity provider (Firebase) used by the Users microservice

##### Break down the file structure into architectural components
- frontend/Dutylist → Mobile/Web app
- backend/ShoppingList → Monolithic REST API
- Modules: auth (JWT), lists (Shoplist, Item), products, utils
- backend/microservices/products → Products microservice (OpenAPI generator)
- backend/microservices/users → Users microservice (Firebase • Public/Private/Auth APIs)
- backend/database → SQL scripts for monolith’s database schema & seed data
- backend/openapi → JSON API contracts for Products & Users services

##### Extract key interactions from the code & README
- Frontend calls monolith for user workflows: login/register, create/view lists, add items
- Monolith:
- Manages user sessions (JWTFilter, SecurityConfig)
- CRUD on lists & items (ListController / ItemController → JPA Repositories)
- Basic product lookup (ProductController → ProductService)
- Monolith delegates to microservices for specialized domains:
- Products microservice (defined by openapi/productsapi.json)
- Users microservice (defined by openapi/usersapi.json)
- Microservices each persist to their own datastore (JPA Repositories)
- Users microservice calls Firebase for token verification (FirebaseConfig)

##### Components
a. Clients
– Web/Mobile UI (Dutylist Next.js + React-Native using Gluestack UI)
b. API layer
– ShoppingList Monolith (Spring Boot)
· Auth module (JWTFilter, AuthController → AuthService)
· Lists module (ListController, ItemController)
· Products module (basic product endpoints)
c. Microservices
– Products microservice (OpenApiGeneratorApplication, ProductsApiController)
– Users microservice (UsersApplication, AuthAPI / PublicAPI / PrivateAPI)
d. Datastores
– Relational DB for monolith (schema & data SQL)
– Separate DBs for each microservice
e. External services
– Firebase Authentication

##### Relationships & data flows
- UI → Monolith: HTTPS requests for all user interactions
- Monolith → Products microservice: HTTP calls per OpenAPI contract
- Monolith → Users microservice: HTTP calls for user/role queries (or direct DB? see code)
- Users microservice → Firebase: JWT token validation / user management
- Each service → own database: JPA writes/reads

##### Architectural patterns & principles
- Hybrid architecture: monolith + microservices
- Layered MVC in Spring Boot (controllers → services → repositories)
- Token-based security (JWT in monolith, Firebase in users service)
- API-first (OpenAPI for microservices)
- Domain separation: auth, lists, products, users

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend
    subgraph "Frontend Layer"
        Dutylist["Dutylist UI\n(Next.js/React Native)"]:::frontend
    end

    %% Monolith
    subgraph "ShoppingList Monolith\n(Spring Boot)"
        MLApp["ShoppingListApplication"]:::monolith
        subgraph "Auth Module"
            AuthCfg["Config"]:::monolith
            AuthCtrl["AuthController"]:::monolith
            AuthDAO["DAO"]:::monolith
            AuthJWT["JWT"]:::monolith
            AuthSvc["Service"]:::monolith
        end
        subgraph "Lists Module"
            ListCtrl["ListController & ItemController"]:::monolith
            ListDAO["Repositories"]:::monolith
            ListDTO["DTOs"]:::monolith
            ListSvc["Services"]:::monolith
        end
        subgraph "Products Module"
            ProdCtrl["ProductController"]:::monolith
            ProdSvc["ProductService"]:::monolith
            ProdDAO["Repositories"]:::monolith
        end
        Utils["Utilities"]:::monolith
    end

    DBMono["Monolith DB\n(SQL Scripts)"]:::database

    %% Products Microservice
    subgraph "Products Microservice\n(Spring Boot)"
        ProdMSApp["OpenApiGeneratorApplication"]:::micro
        ProdAPI["ProductsApiController & Service"]:::micro
        ProdEntity["Entities"]:::micro
        ProdRepo["Repositories"]:::micro
    end
    DBProd["Products DB"]:::database

    %% Users Microservice
    subgraph "Users Microservice\n(Spring Boot)"
        UserMSApp["UsersApplication"]:::micro
        AuthAPI["Auth API"]:::micro
        PubAPI["Public API"]:::micro
        PrivAPI["Private API"]:::micro
        FirebaseCfg["FirebaseConfig"]:::micro
        UserRepo["UserRepository"]:::micro
    end
    DBUser["Users DB"]:::database

    %% External Service
    Firebase["Firebase Authentication"]:::external

    %% Connections
    Dutylist -->|"HTTPS"| MLApp
    MLApp -->|"writes/reads"| DBMono
    MLApp -->|"uses Auth Module"| AuthSvc
    AuthSvc --> AuthDAO
    AuthSvc --> AuthJWT
    MLApp --> ListCtrl
    ListCtrl --> ListSvc
    ListSvc --> ListDAO
    MLApp --> ProdCtrl
    ProdCtrl --> ProdSvc
    ProdSvc --> ProdDAO
    MLApp --> Utils

    MLApp -->|"HTTP /openapi/productsapi.json"| ProdMSApp
    ProdMSApp --> ProdAPI
    ProdAPI --> ProdEntity
    ProdEntity --> ProdRepo
    ProdMSApp --> DBProd

    MLApp -->|"HTTP /openapi/usersapi.json"| UserMSApp
    UserMSApp --> AuthAPI
    UserMSApp --> PubAPI
    UserMSApp --> PrivAPI
    AuthAPI --> UserRepo
    AuthAPI --> FirebaseCfg
    AuthAPI -->|"verifies JWT"| Firebase
    UserMSApp --> DBUser

    %% Click Events
    click Dutylist "https://github.com/adriantd3/shoppinglist/tree/main/frontend/Dutylist"
    click MLApp "https://github.com/adriantd3/shoppinglist/blob/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/ShoppingListApplication.java"
    click AuthCfg "https://github.com/adriantd3/shoppinglist/tree/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/auth/config"
    click AuthCtrl "https://github.com/adriantd3/shoppinglist/blob/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/auth/controller/AuthController.java"
    click AuthDAO "https://github.com/adriantd3/shoppinglist/tree/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/auth/dao"
    click AuthJWT "https://github.com/adriantd3/shoppinglist/tree/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/auth/jwt"
    click AuthSvc "https://github.com/adriantd3/shoppinglist/tree/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/auth/service"
    click ListCtrl "https://github.com/adriantd3/shoppinglist/tree/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/lists/controller"
    click ListDAO "https://github.com/adriantd3/shoppinglist/tree/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/lists/dao"
    click ListDTO "https://github.com/adriantd3/shoppinglist/tree/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/lists/dto"
    click ListSvc "https://github.com/adriantd3/shoppinglist/tree/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/lists/service"
    click ProdCtrl "https://github.com/adriantd3/shoppinglist/blob/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/products/ProductController.java"
    click ProdSvc "https://github.com/adriantd3/shoppinglist/blob/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/products/ProductService.java"
    click ProdDAO "https://github.com/adriantd3/shoppinglist/tree/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/products/dao"
    click Utils "https://github.com/adriantd3/shoppinglist/tree/main/backend/ShoppingList/src/main/java/org/adriantd/shoppinglist/utils"
    click DBMono "https://github.com/adriantd3/shoppinglist/blob/main/backend/database/db_structure.sql"
    click DBMono "https://github.com/adriantd3/shoppinglist/blob/main/backend/database/db_data.sql"
    click ProdMSApp "https://github.com/adriantd3/shoppinglist/blob/main/backend/microservices/products/src/main/java/org/openapitools/OpenApiGeneratorApplication.java"
    click ProdAPI "https://github.com/adriantd3/shoppinglist/blob/main/backend/microservices/products/src/main/java/org/openapitools/api/ProductsApiController.java"
    click ProdAPI "https://github.com/adriantd3/shoppinglist/blob/main/backend/microservices/products/src/main/java/org/openapitools/api/ProductsService.java"
    click ProdEntity "https://github.com/adriantd3/shoppinglist/tree/main/backend/microservices/products/src/main/java/org/openapitools/entity"
    click ProdRepo "https://github.com/adriantd3/shoppinglist/tree/main/backend/microservices/products/src/main/java/org/openapitools/repository"
    click UserMSApp "https://github.com/adriantd3/shoppinglist/blob/main/backend/microservices/users/src/main/java/org/dutylist/users/UsersApplication.java"
    click AuthAPI "https://github.com/adriantd3/shoppinglist/tree/main/backend/microservices/users/src/main/java/org/dutylist/users/api/auth"
    click PubAPI "https://github.com/adriantd3/shoppinglist/tree/main/backend/microservices/users/src/main/java/org/dutylist/users/api/pub"
    click PrivAPI "https://github.com/adriantd3/shoppinglist/tree/main/backend/microservices/users/src/main/java/org/dutylist/users/api/priv"
    click FirebaseCfg "https://github.com/adriantd3/shoppinglist/blob/main/backend/microservices/users/src/main/java/org/dutylist/users/security/FirebaseConfig.java"
    click UserRepo "https://github.com/adriantd3/shoppinglist/blob/main/backend/microservices/users/src/main/java/org/dutylist/users/repositories/UserRepository.java"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef monolith fill:#DFFFE0,stroke:#28a745,color:#155724;
    classDef micro fill:#FFE8A0,stroke:#fd7e14,color:#c63d0f;
    classDef database fill:#F0F0F0,stroke:#6c757d,color:#343a40,shape:cylinder;
    classDef external fill:#E0F7FA,stroke:#17a2b8,color:#0c5460,shape:cloud;
```
