# nesohq/bgce-archive architecture

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

- Interactive diagram: https://gitdiagram.com/nesohq/bgce-archive
- Repository: https://github.com/nesohq/bgce-archive

## Overview

##### Project type and purpose
- This is a full-stack, community-vault monorepo housing:
– Two front-end apps (Vue “archive-admin” and Next.js “archive-client”)
– Three Go microservices (“cortex”, “ecommerce”, plus a “skeleton” service template)
– Shared docs, scripts, and scaffolding
- Purpose: archive and serve Go community content via REST APIs and web UIs.

##### File structure
- Top-level UIs:
– archive-admin (Vue-based admin dashboard, Cypress e2e tests)
– archive-client (Next.js client portal)
- Microservices: all Go modules, each with:
– cmd/ (entrypoints)
– config/ (load environment, config)
– rest/ (HTTP handlers, middlewares, Swagger UI)
– domain packages (e.g. cortex/cache, cortex/category)
– persistence: ent ORM under ent/, database models under database/
– messaging: rabbitmq/
– util/, logger/, apm/
- Infrastructure scripts (scripts/), documentation (docs/).

##### Readme insights
- “cortex” handles category domain logic (CRUD, caching, message bus)
- “ecommerce” is a tutorial e-commerce API (products, reviews, users)
- “skeleton” is a template to bootstrap new microservices.

##### Main components
A. Clients & UIs
1. archive-client (Next.js SPA)
2. archive-admin (Vue SPA)
1. cortex service
2. ecommerce service
3. (optionally) skeleton template service
C. Data stores
1. MySQL/Postgres for each service (separate schemas)
2. Redis (for cache toggles in cortex)
D. Message broker
– RabbitMQ cluster for pub/sub events
E. Observability & infra
– APM agent (traces from microservices)
– Swagger UI (embedded in each service’s REST layer)
F. Documentation site (static docs served via GitHub Pages)

##### Relationships & data flows
- Browsers → HTTP(S) → archive-client / archive-admin
- UIs → invoke REST endpoints on cortex/ecommerce via API URLs
- REST handlers → domain services → ent ORM → MySQL
- cortex service → optional Redis cache reads/writes
- Domain events (e.g. “category created”) → RabbitMQ → other subscribers
- Services report spans/traces → APM back end

##### Architectural patterns & principles
- Hexagonal/Ports & Adapters: each service isolates domain logic (cache, repo, messaging are ports)
- Layered REST: handlers → services → repository → database
- Shared scaffolding (skeleton) enforces consistent structure across services
- CI via GitHub Actions (lint, docs build, Go tests)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "Public Internet"
        archive_client[/archive-client/]:::ui
        archive_admin[/archive-admin/]:::ui
    end

    %% Services Layer
    subgraph "Internal Network"
        subgraph "Cortex Service" 
            cortex["cortex:8080"]:::service
            cortex_cmd["cmd/"] 
            cortex_config["config/"]
            cortex_rest["rest/"]
            cortex_category["category/"]
            cortex_cache["cache/"]
            cortex_ent["ent/"]
            cortex_rabbitmq["rabbitmq/"]
            cortex_apm["apm/"]
            cortex_logger["logger/"]
        end

        subgraph "Ecommerce Service"
            ecommerce["ecommerce:8080"]:::service
            ecommerce_cmd["cmd/serve.go"]
            ecommerce_config["config/"]
            ecommerce_rest["rest/"]
            ecommerce_database["database/"]
            ecommerce_util["util/create_jwt.go"]
        end

        subgraph "Skeleton Template" 
            skeleton["skeleton (template)"]:::serviceDashed
            skeleton_cmd["cmd/"]
            skeleton_config["config/"]
            skeleton_rest["rest/"]
            skeleton_repo["repo/"]
            skeleton_rabbitmq["rabbitmq/"]
            skeleton_apm["apm/"]
            skeleton_logger["logger/"]
        end
    end

    %% Storage Layer
    subgraph "Storage"
        db_cortex[(MySQL Cortex)]:::storage
        db_ecom[(MySQL Ecommerce)]:::storage
        redis[(Redis Cache)]:::storage
    end

    %% Messaging & Observability
    subgraph "Infrastructure"
        rabbit[(RabbitMQ)]:::messaging
        apm[(APM Backend)]:::observability
        docs["Docs Site"]:::docs
    end

    %% Scripts & CI
    scripts_docs["scripts/docs/"] 
    scripts_project["scripts/project/"] 
    scripts_kraken["scripts/krakencli/"] 
    ci_workflows[".github/workflows/"] 
    ci_cache_go[".github/actions/go-cache/"] 
    ci_cache_md[".github/actions/cargo-mdbook-cache/"]

    %% Relationships
    archive_client -->|"GET /categories"| cortex
    archive_client -->|"GET /products"| ecommerce
    archive_admin -->|"GET /categories"| cortex
    cortex -->|"Ent ORM calls"| db_cortex
    ecommerce -->|"ORM calls"| db_ecom
    cortex -->|"CACHE GET/SET"| redis
    cortex -->|"PUBLISH event:CategoryCreated"| rabbit
    ecommerce -->|"PUBLISH event:OrderCreated"| rabbit
    cortex -->|"Traces"| apm
    ecommerce -->|"Traces"| apm
    skeleton -.->|"Template only"| cortex
    skeleton -.->|"Template only"| ecommerce
    docs -->|"Static site"| archive_client
    scripts_docs --> docs
    scripts_project --> skeleton
    scripts_kraken --> skeleton
    ci_workflows --> cortex
    ci_workflows --> ecommerce
    ci_cache_go --> ci_workflows
    ci_cache_md --> ci_workflows

    %% Click Events
    click archive_client "https://github.com/nesohq/bgce-archive/tree/master/archive-client/"
    click archive_admin "https://github.com/nesohq/bgce-archive/tree/master/archive-admin/"
    click cortex_cmd "https://github.com/nesohq/bgce-archive/tree/master/cortex/cmd/"
    click cortex_config "https://github.com/nesohq/bgce-archive/tree/master/cortex/config/"
    click cortex_rest "https://github.com/nesohq/bgce-archive/tree/master/cortex/rest/"
    click cortex_category "https://github.com/nesohq/bgce-archive/tree/master/cortex/category/"
    click cortex_cache "https://github.com/nesohq/bgce-archive/tree/master/cortex/cache/"
    click cortex_ent "https://github.com/nesohq/bgce-archive/tree/master/cortex/ent/"
    click cortex_rabbitmq "https://github.com/nesohq/bgce-archive/tree/master/cortex/rabbitmq/"
    click cortex_apm "https://github.com/nesohq/bgce-archive/tree/master/cortex/apm/"
    click cortex_logger "https://github.com/nesohq/bgce-archive/tree/master/cortex/logger/"
    click ecommerce_cmd "https://github.com/nesohq/bgce-archive/blob/master/ecommerce/cmd/serve.go"
    click ecommerce_config "https://github.com/nesohq/bgce-archive/tree/master/ecommerce/config/"
    click ecommerce_rest "https://github.com/nesohq/bgce-archive/tree/master/ecommerce/rest/"
    click ecommerce_database "https://github.com/nesohq/bgce-archive/tree/master/ecommerce/database/"
    click ecommerce_util "https://github.com/nesohq/bgce-archive/blob/master/ecommerce/util/create_jwt.go"
    click skeleton_cmd "https://github.com/nesohq/bgce-archive/tree/master/skeleton/cmd/"
    click skeleton_config "https://github.com/nesohq/bgce-archive/tree/master/skeleton/config/"
    click skeleton_rest "https://github.com/nesohq/bgce-archive/tree/master/skeleton/rest/"
    click skeleton_repo "https://github.com/nesohq/bgce-archive/tree/master/skeleton/repo/"
    click skeleton_rabbitmq "https://github.com/nesohq/bgce-archive/tree/master/skeleton/rabbitmq/"
    click skeleton_apm "https://github.com/nesohq/bgce-archive/tree/master/skeleton/apm/"
    click skeleton_logger "https://github.com/nesohq/bgce-archive/tree/master/skeleton/logger/"
    click docs "https://github.com/nesohq/bgce-archive/tree/master/docs/"
    click scripts_docs "https://github.com/nesohq/bgce-archive/tree/master/scripts/docs/"
    click scripts_project "https://github.com/nesohq/bgce-archive/tree/master/scripts/project/"
    click scripts_kraken "https://github.com/nesohq/bgce-archive/tree/master/scripts/krakencli/"
    click ci_workflows "https://github.com/nesohq/bgce-archive/tree/master/.github/workflows/"
    click ci_cache_go "https://github.com/nesohq/bgce-archive/tree/master/.github/actions/go-cache/"
    click ci_cache_md "https://github.com/nesohq/bgce-archive/tree/master/.github/actions/cargo-mdbook-cache/"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef serviceDashed fill:#90EE90,stroke:#333,stroke-dasharray: 5 5,stroke-width:1px;
    classDef storage fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef messaging fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef observability fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef docs fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
