# killercavin/brightside architecture

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

- Interactive diagram: https://gitdiagram.com/killercavin/brightside
- Repository: https://github.com/killercavin/brightside

## Overview

##### Project type and purpose
- BrightSide Stores is a full-stack e-commerce/storefront application.
- The frontend is a Next.js/React SPA with server-side rendering and theming.
- The backend is a Ktor (Kotlin) REST API exposing endpoints for products, categories, and cart.
- A relational database (e.g. PostgreSQL) stores domain data.

##### File structure
- Top-level directories:
– backend/: Ktor application with configs, controllers, services, models, routes, tests
– frontend/: Next.js app with pages, components, theming, public assets
- Backend patterns: layered architecture (Routing → Controllers → Services → Data/Models)
- Key config files: application.yaml, EnvConfig, DatabaseFactory, Serialization, Security
- Frontend patterns: app/layout + page.tsx, reusable components (Header, Footer, Hero), ThemeProvider
- Build tools: Gradle wrapper for backend, pnpm workspace for frontend

##### README for additional insights
- README simply names the project, but code and file names imply standard e-commerce operations:
– Product listing & management
– Category management
– Cart operations

##### Main components and interactions
a. Client & Browser
– Users interact via browser, triggering SSR or API calls
b. Frontend (Next.js)
– Pages (layout.tsx, page.tsx) render UI, import ThemeProvider, Header, Footer, Hero
– Fetches data from backend REST endpoints (/api/products, /api/categories, /api/cart)
c. Backend (Ktor REST API)
– Routing layer (CartRoutes, ProductRoutes, CategoryRoutes)
– Controllers (CartController, ProductController, CategoryController) handle HTTP requests
– Services encapsulate business logic (CartService, ProductService, CategoryService)
– Data layer: Exposed ORM tables (ProductTable, CategoryTable) + Models → Database
– Config modules: DatabaseFactory (connection pool), Serialization (JSON), Security (auth), EnvConfig
d. Database
– Relational store for products, categories, cart entries
e. External and support services
– Logging (logback)
– Environment variables (.env via EnvConfig)
– Static assets served by Next.js from public/assets

##### Architectural patterns & design principles
- Layered service architecture in backend (separate web, service, data layers)
- Modular routing grouping per resource (products, categories, cart)
- Next.js SSR/SSG for SEO + React component composition + theming
- Configuration by code (Kotlin config classes) and YAML for environment
- Dependency injection via constructor parameters in services/controllers

##### Essential elements
- Clear labels on all components (e.g., “ProductService”, “CategoryController”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Browser"]:::client
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        Layout["Next.js Layout"]:::frontend
        Page["Next.js Home Page"]:::frontend
        Theme["ThemeProvider"]:::frontend
        Header["Header"]:::frontend
        Footer["Footer"]:::frontend
        Hero["Hero"]:::frontend
        Assets["Static Assets"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        RoutingCfg["Routing Config"]:::backend_light
        ProductRoutes["ProductRoutes"]:::backend_light
        CategoryRoutes["CategoryRoutes"]:::backend_light
        CartRoutes["CartRoutes"]:::backend_light
    end

    %% Controllers
    subgraph "Controller Layer"
        ProdCtrl["ProductController"]:::backend_mid
        CatCtrl["CategoryController"]:::backend_mid
        CartCtrl["CartController"]:::backend_mid
    end

    %% Services
    subgraph "Business Logic Layer"
        ProdSvc["ProductService"]:::backend_dark
        CatSvc["CategoryService"]:::backend_dark
        CartSvc["CartService"]:::backend_dark
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        DBFactory["DatabaseFactory"]:::support
        DBConfig["Database Config"]:::support
        EnvCfg["EnvConfig"]:::support
        SerCfg["Serialization"]:::support
        SecCfg["Security"]:::support
        ProdTable["ProductTable"]:::data
        CatTable["CategoryTable"]:::data
        CartTable["CartTable"]:::data
    end

    %% Persistence
    DB["PostgreSQL"]:::db

    %% Ancillary Services
    subgraph "Ancillary Services"
        Log["Logging (Logback)"]:::support
        Yaml["application.yaml"]:::support
        LogbackCfg["logback.xml"]:::support
    end

    %% Bootstrap
    subgraph "Bootstrap"
        App["Application.kt"]:::support
    end

    %% Connections
    Browser -->|SSR/HTTP| Layout
    Layout --> Page
    Page --> Theme
    Page --> Header
    Page --> Footer
    Page --> Hero
    Page -->|serves| Assets

    Page -->|GET /products → JSON| ProductRoutes
    Page -->|GET /categories → JSON| CategoryRoutes
    Page -->|GET /cart → JSON| CartRoutes

    App --> RoutingCfg
    App --> DBFactory
    App --> SerCfg
    App --> SecCfg
    App --> EnvCfg
    Log --> App
    Yaml --> App
    LogbackCfg --> App

    RoutingCfg --> ProductRoutes
    RoutingCfg --> CategoryRoutes
    RoutingCfg --> CartRoutes

    ProductRoutes --> ProdCtrl
    CategoryRoutes --> CatCtrl
    CartRoutes --> CartCtrl

    ProdCtrl --> ProdSvc
    CatCtrl --> CatSvc
    CartCtrl --> CartSvc

    ProdSvc --> ProdTable
    CatSvc --> CatTable
    CartSvc --> CartTable

    DBFactory --> DB
    DBConfig --> DBFactory
    EnvCfg --> DBFactory
    SerCfg --> ProductRoutes
    SecCfg --> RoutingCfg

    ProdTable --> DB
    CatTable --> DB
    CartTable --> DB

    %% Click Events
    click Layout "https://github.com/killercavin/brightside/blob/main/frontend/src/app/layout.tsx"
    click Page "https://github.com/killercavin/brightside/blob/main/frontend/src/app/page.tsx"
    click Theme "https://github.com/killercavin/brightside/blob/main/frontend/src/components/theme/ThemeProvider.tsx"
    click Header "https://github.com/killercavin/brightside/blob/main/frontend/src/components/Header.tsx"
    click Footer "https://github.com/killercavin/brightside/blob/main/frontend/src/components/Footer.tsx"
    click Hero "https://github.com/killercavin/brightside/blob/main/frontend/src/components/Hero.tsx"
    click Assets "https://github.com/killercavin/brightside/tree/main/frontend/public/assets"
    click App "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/Application.kt"
    click RoutingCfg "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/configs/Routing.kt"
    click DBFactory "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/configs/DatabaseFactory.kt"
    click DBConfig "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/configs/Database.kt"
    click EnvCfg "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/configs/EnvConfig.kt"
    click SerCfg "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/configs/Serialization.kt"
    click SecCfg "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/configs/Security.kt"
    click ProductRoutes "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/routes/ProductRoutes.kt"
    click CategoryRoutes "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/routes/CategoryRoutes.kt"
    click CartRoutes "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/routes/CartRoutes.kt"
    click ProdCtrl "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/controllers/ProductController.kt"
    click CatCtrl "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/controllers/CategoryController.kt"
    click CartCtrl "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/controllers/CartController.kt"
    click ProdSvc "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/services/ProductService.kt"
    click CatSvc "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/services/CategoryService.kt"
    click CartSvc "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/services/CartService.kt"
    click ProdTable "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/models/table/ProductTable.kt"
    click CatTable "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/models/table/CategoryTable.kt"
    click CartTable "https://github.com/killercavin/brightside/blob/main/backend/src/main/kotlin/com/brightside/backend/models/table/CategoryTable.kt"
    click Yaml "https://github.com/killercavin/brightside/blob/main/backend/src/main/resources/application.yaml"
    click LogbackCfg "https://github.com/killercavin/brightside/blob/main/backend/src/main/resources/logback.xml"

    %% Styles
    classDef client fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend_light fill:#90EE90,stroke:#000,stroke-width:1px
    classDef backend_mid fill:#32CD32,stroke:#000,stroke-width:1px
    classDef backend_dark fill:#006400,stroke:#000,stroke-width:1px
    classDef data fill:#FFD700,stroke:#000,stroke-width:1px
    classDef support fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef db fill:#8B4513,stroke:#000,stroke-width:1px,shape:cylinder
```
