# takuma123-type/history-server architecture

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

- Interactive diagram: https://gitdiagram.com/takuma123-type/history-server
- Repository: https://github.com/takuma123-type/history-server

## Overview

##### Project type and purpose
- This is a Ruby on Rails monolith serving both:
– A JSON API (“app/controllers/api/…”, jbuilder views)
– A simple PWA front-end (in “app/views/pwa” with manifest & service-worker)
- It exposes resources (CoreStacks, Histories, Infrastructures, Positions, Scales, Sessions) via REST.
- It uses JWT for auth, ActiveRecord + MySQL, Docker+Compose for local/dev/prod, RSpec/tests, CI via GitHub Actions.

##### File structure & architectural patterns
- MVC Layers:
– Controllers (API): HTTP entry points
– Models: ActiveRecord entities
– Views: JSON builders + PWA assets
- Service & Use-Case Layers:
– “app/usecases” implements application business logic, decoupling controllers from models.
– “app/services/jwt_service.rb” handles token creation/validation.
- Background Jobs: “app/jobs” (ActiveJob), Mailers.
- Configuration: Puma web server, CORS, credentials, Dockerfiles, Compose.

##### Main components & boundaries
A. Client Layer
– Browser/PWA or external API clients
B. Web Tier
– Reverse proxy/load-balancer (optional NGINX in production)
– Puma app server running Rails
C. Application Layer (Rails monolith)
– Controllers → Use-Case layer → Service layer → Models
– Views (JSON via Jbuilder, PWA assets via asset-pipeline)
– ActiveJob for background processing
– Mailers for notifications
D. Data Layer
– MySQL (configured via config/database.yml, Dockerfile.mysql)
– ActiveStorage/local file storage
E. Dev/Ops & CI
– Docker Compose (compose.yml, Dockerfile.dev/prod)
– GitHub Actions (CI workflow)
– Utilities: RuboCop, Brakeman, RSpec

##### Relationships & data flow
1. Client → HTTP(S) → NGINX/load-balancer → Puma → Rails Router
2. Rails Router dispatches to API Controllers or PWA Routes
3. Controller calls a Use-Case (e.g., LogInUsecase → JwtService → Session model)
4. Use-Case interacts with ActiveRecord models (CRUD in MySQL)
5. Controller renders JSON via Jbuilder
6. For background tasks: Controller or Use-Case enqueues an ActiveJob → Job Adapter → Worker
7. Assets (CSS/JS/images) served via asset pipeline or CDN
8. Docker Compose ties Rails container, MySQL container, possibly Redis (if used) together

##### Architectural patterns & principles
- Layered / Onion / Hexagonal style:
– Controllers (adapters/entry)
– Use-Cases (application core)
– Services (domain utilities)
– Models (ORM / persistence)
- Single codebase monolith: all layers in one Rails app
- Use of Docker for environment parity

##### Essential details to capture
- Authentication flow via JWTService
- UseCase layer encapsulating business rules
- Asset pipeline/PWA service-worker serving static content
- Docker Compose as the orchestration point in dev/prod
- CI pipeline triggering tests, linting, builds

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Browser / PWA"]:::ui
        External["Third-party API Clients"]:::ui
    end

    %% Web Tier
    subgraph "Web Tier"
        NGINX["Nginx / Load Balancer"]:::ops
        Puma["Puma App Server"]:::app
    end

    %% Rails Application
    subgraph "Rails Application"
        subgraph Controllers
            AppCtrl["ApplicationController"]:::app
            ApiCtrls["API Controllers"]:::app
        end
        subgraph UseCases
            BaseUC["ApplicationUsecase"]:::app
            ApiUCs["API Usecases"]:::app
        end
        subgraph Services
            JWT["JwtService"]:::app
        end
        subgraph Models
            ARModels["ActiveRecord Models"]:::data
        end
        subgraph Views
            JSONViews["Jbuilder Views"]:::app
            PWAAssets["PWA Front-End Assets"]:::ui
        end
        subgraph Jobs
            BackgroundJobs["Background Jobs"]:::app
            Mailers["Mailers"]:::app
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        MySQL["MySQL Database"]:::data
        Storage["ActiveStorage / File Storage"]:::data
    end

    %% Dev/Ops & CI
    subgraph "Dev/Ops & CI"
        DockerCompose["Docker Compose"]:::ops
        CI["GitHub Actions CI"]:::ops
    end

    %% Connections
    Browser -->|"HTTPS"| NGINX
    External -->|"HTTPS"| NGINX
    NGINX -->|"Proxy HTTP"| Puma
    Puma -->|"Rails Router"| ApiCtrls
    ApiCtrls -->|"calls"| BaseUC
    ApiCtrls -->|"calls"| ApiUCs
    BaseUC -->|"uses"| JWT
    ApiUCs -->|"CRUD / SQL"| MySQL
    ApiUCs -->|"manipulates"| ARModels
    ARModels -->|"stores files"| Storage
    ApiCtrls -->|"renders JSON"| JSONViews
    ApiCtrls -->|"serves assets"| PWAAssets
    ApiCtrls -->|"enqueue"| BackgroundJobs
    BackgroundJobs -->|"sends"| Mailers
    DockerCompose --> Puma
    DockerCompose --> MySQL
    CI --> DockerCompose

    %% Click Events
    click ApiCtrls "https://github.com/takuma123-type/history-server/blob/main/app/controllers/api/*.rb"
    click AppCtrl "https://github.com/takuma123-type/history-server/blob/main/app/controllers/application_controller.rb"
    click ARModels "https://github.com/takuma123-type/history-server/blob/main/app/models/*.rb"
    click JSONViews "https://github.com/takuma123-type/history-server/blob/main/app/views/api/**/*.json.jbuilder"
    click PWAAssets "https://github.com/takuma123-type/history-server/blob/main/app/views/pwa/manifest.json.erb"
    click PWAAssets "https://github.com/takuma123-type/history-server/blob/main/app/views/pwa/service-worker.js"
    click BaseUC "https://github.com/takuma123-type/history-server/blob/main/app/usecases/application_usecase.rb"
    click ApiUCs "https://github.com/takuma123-type/history-server/blob/main/app/usecases/api/*.rb"
    click JWT "https://github.com/takuma123-type/history-server/blob/main/app/services/jwt_service.rb"
    click BackgroundJobs "https://github.com/takuma123-type/history-server/blob/main/app/jobs/application_job.rb"
    click Mailers "https://github.com/takuma123-type/history-server/blob/main/app/mailers/application_mailer.rb"
    click DockerCompose "https://github.com/takuma123-type/history-server/blob/main/compose.yml"
    click CI "https://github.com/takuma123-type/history-server/blob/main/.github/workflows/pr-agent.yaml"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0969DA,color:#0969DA
    classDef app fill:#DFFFE0,stroke:#22863A,color:#22863A
    classDef data fill:#FFF5B1,stroke:#D4A72C,color:#82540C
    classDef ops fill:#EDEEF0,stroke:#57606A,color:#24292F
```
