# kgcorner/topspin architecture

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

- Interactive diagram: https://gitdiagram.com/kgcorner/topspin
- Repository: https://github.com/kgcorner/topspin

## Overview

##### Project Type and Purpose
- This is a full-stack, cloud-native microservices application (“Topspin”) that implements an online mall.
- Key parts: an Angular “admin-client” frontend, a Spring-based microservices backend (auth, user, store, offer, product-offer, agent), a config service, a discovery service, an API gateway, plus common libraries and utilities.

##### High-Level Components
- Client Layer
- admin-client (Angular app)
- Edge Layer
- API Gateway (“topspin-gateway-service”)
- Infrastructure Services
- Configuration Service (Spring Cloud Config)
- Service Registry / Discovery (Eureka)
- Health/Monitoring (health endpoint package)
- Domain Services (each a Spring Boot microservice)
- Auth Service
- User Service
- Store Service
- Offer Service
- Product-Offer Service
- Agent Service
- Data Stores
- MongoDB (user-service, store-service, auth-service via mongo-port modules)
- MySQL (offer-service)
- Redis (cache via common/topspin-common RedisCache)
- External Integrations
- OAuth providers (Facebook, Google via auth-service modules)
- AWS S3 (via aws-utilities)

##### Relationships & Data Flows
- The Angular client sends all HTTP(S) requests to the API Gateway.
- API Gateway consults Discovery to locate service instances, then routes requests to the appropriate microservice.
- On startup each microservice:
a. Fetches its configuration from Config Service
b. Registers its endpoint(s) with Discovery
- Microservices interact only through well-defined REST APIs.
- Each microservice uses its own persistence module (MySQL or Mongo) via common persistence libraries.
- Common libraries (topspin-common, mongodb-util, mysql-util, aws-utilities) are build-time dependencies for domain modules.
- Caching layer (Redis) used by services via the RedisCache handler.
- OAuth flows contact external Facebook/Google endpoints.

##### Architectural Patterns & Principles
- Microservices pattern: each bounded context deployed independently.
- Spring Cloud ecosystem: Config Service, Eureka Discovery, Gateway.
- Shared libraries only for cross-cutting concerns (security, persistence, HATEOAS, caching).
- Infrastructure as code: Docker-Compose and Dockerfiles for each service.
- CI/CD: Travis, Sonar, Codecov badges in README.
- Integration testing with Cucumber/TestNG in separate “integration-tests” modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Client Layer"
        AdminClient["Admin Client"]:::client
    end

    subgraph "Edge Layer"
        Gateway["API Gateway\n(topspin-gateway-service)"]:::edge
    end

    subgraph "Infrastructure Layer"
        ConfigService["Config Service\n(Spring Cloud Config)"]:::edge
        DiscoveryService["Service Registry\n(Eureka)"]:::edge
        HealthService["Health/Monitoring"]:::edge
    end

    subgraph "Domain Services"
        AuthService["Auth Service\n(Spring Boot)"]:::service
        UserService["User Service\n(Spring Boot)"]:::service
        StoreService["Store Service\n(Spring Boot)"]:::service
        OfferService["Offer Service\n(Spring Boot)"]:::service
        ProdOfferService["Product-Offer Service\n(Spring Boot)"]:::service
        AgentService["Agent Service\n(Spring Boot)"]:::service
    end

    subgraph "Data Stores"
        AuthDB["MongoDB"]:::datastore
        UserDB["MongoDB"]:::datastore
        StoreDB["MongoDB"]:::datastore
        OfferDB["MySQL"]:::datastore
        RedisCache["Redis"]:::datastore
    end

    subgraph "External Integrations"
        Facebook["Facebook OAuth"]:::external
        Google["Google OAuth"]:::external
        S3["AWS S3"]:::external
    end

    subgraph "Integration Tests"
        IT_Auth["Auth Service Tests"]:::external
        IT_User["User Service Tests"]:::external
        IT_Util["Integration Test Utils"]:::external
    end

    %% Client to Gateway
    AdminClient -->|"HTTP(S) calls"| Gateway

    %% Gateway to Infrastructure
    Gateway -->|"fetch config"| ConfigService
    Gateway -->|"Eureka registration"| DiscoveryService

    %% Gateway routing to services
    Gateway -->|"Routes API calls"| AuthService
    Gateway -->|"Routes API calls"| UserService
    Gateway -->|"Routes API calls"| StoreService
    Gateway -->|"Routes API calls"| OfferService
    Gateway -->|"Routes API calls"| ProdOfferService
    Gateway -->|"Routes API calls"| AgentService

    %% Services startup flows
    AuthService -->|"fetch config"| ConfigService
    UserService -->|"fetch config"| ConfigService
    StoreService -->|"fetch config"| ConfigService
    OfferService -->|"fetch config"| ConfigService
    ProdOfferService -->|"fetch config"| ConfigService
    AgentService -->|"fetch config"| ConfigService

    AuthService -->|"Eureka registration"| DiscoveryService
    UserService -->|"Eureka registration"| DiscoveryService
    StoreService -->|"Eureka registration"| DiscoveryService
    OfferService -->|"Eureka registration"| DiscoveryService
    ProdOfferService -->|"Eureka registration"| DiscoveryService
    AgentService -->|"Eureka registration"| DiscoveryService

    %% Service to datastore
    AuthService -->|"uses"| AuthDB
    UserService -->|"uses"| UserDB
    StoreService -->|"uses"| StoreDB
    OfferService -->|"uses"| OfferDB
    AuthService -->|"cache via"| RedisCache
    UserService -->|"cache via"| RedisCache
    StoreService -->|"cache via"| RedisCache
    OfferService -->|"cache via"| RedisCache
    ProdOfferService -->|"cache via"| RedisCache
    AgentService -->|"cache via"| RedisCache

    %% External integrations
    AuthService -->|"OAuth flow"| Facebook
    AuthService -->|"OAuth flow"| Google
    StoreService -->|"uses AWS utilities"| S3

    %% Integration tests
    IT_Auth -->|"test via Gateway or direct"| Gateway
    IT_User -->|"test via Gateway or direct"| Gateway
    IT_Util -->|"support tests"| IT_Auth
    IT_Util -->|"support tests"| IT_User

    %% Click Events
    click AdminClient "https://github.com/kgcorner/topspin/tree/master/admin-client/"
    click Gateway "https://github.com/kgcorner/topspin/tree/master/packaging/docker-packaging/topspin-gateway-docker/"
    click ConfigService "https://github.com/kgcorner/topspin/tree/master/config-service/"
    click DiscoveryService "https://github.com/kgcorner/topspin/tree/master/discovery-service/"
    click HealthService "https://github.com/kgcorner/topspin/tree/master/topspin-health-package/"
    click AuthService "https://github.com/kgcorner/topspin/tree/master/auth-service-modules/auth-service/"
    click UserService "https://github.com/kgcorner/topspin/tree/master/user-service-module/user-service/"
    click StoreService "https://github.com/kgcorner/topspin/tree/master/stores-service-module/store-service/"
    click OfferService "https://github.com/kgcorner/topspin/tree/master/offer-service-module/offer-service/"
    click ProdOfferService "https://github.com/kgcorner/topspin/tree/master/packaging/executable-jar-packaging/spring-product-offer-service/"
    click AgentService "https://github.com/kgcorner/topspin/tree/master/ecom-agent-service/"
    click AuthDB "https://github.com/kgcorner/topspin/tree/master/common/mongodb-util/"
    click UserDB "https://github.com/kgcorner/topspin/tree/master/user-service-module/user-service-mongo-port/"
    click StoreDB "https://github.com/kgcorner/topspin/tree/master/stores-service-module/store-mongo-port/"
    click OfferDB "https://github.com/kgcorner/topspin/tree/master/offer-service-module/offer-service-mysql-port/"
    click RedisCache "https://github.com/kgcorner/topspin/tree/master/aws-utilities/"
    click Facebook "https://github.com/kgcorner/topspin/tree/master/auth-service-modules/auth-service/"
    click Google "https://github.com/kgcorner/topspin/tree/master/auth-service-modules/auth-service/"
    click S3 "https://github.com/kgcorner/topspin/tree/master/aws-utilities/"
    click IT_Auth "https://github.com/kgcorner/topspin/tree/master/integration-tests/authservice-tests/"
    click IT_User "https://github.com/kgcorner/topspin/tree/master/integration-tests/user-service-tests/"
    click IT_Util "https://github.com/kgcorner/topspin/tree/master/integration-tests/integration-test-util/"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef edge fill:#FFA500,stroke:#333,stroke-width:1px
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px
    classDef datastore fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#D8BFD8,stroke:#333,stroke-width:1px
```
