# taira0222/juku-cloud-backend architecture

> Architecture diagram of the GitHub repository taira0222/juku-cloud-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/taira0222/juku-cloud-backend
- Repository: https://github.com/taira0222/juku-cloud-backend

## Overview

##### Project type and purpose
- This is a Ruby on Rails API-only application (no embedded frontend).
- It exposes a versioned REST API (`app/controllers/api/v1/*`) to manage resources (students, teachers, invites, lesson notes, student traits, dashboards).
- It uses token-based authentication (Devise + DeviseTokenAuth).
- It persists data in a relational database and uploads files (if any) via ActiveStorage.
- It runs on Docker in AWS ECS, with CI/CD on GitHub Actions, and relies on background jobs for asynchronous processing.

##### File structure for architectural clues
- `app/controllers/api/v1` → versioned API boundary
- `app/services`, `app/queries`, `app/serializers` → layered, service‐oriented, hexagonal flavor (thin controllers, POJO services, query objects, presenters/serializers)
- `config/storage.yml` → ActiveStorage (local vs S3)
- `db/queue_schema.rb` → jobs backed by DB (ActiveJob + DelayedJob or similar)
- `Dockerfile` + `ecs/taskdef.json` → containerized deployment in ECS
- `config/routes.rb` → entrypoint mapping controllers to URL paths
- `Gemfile` → shows core technologies: Rails, Devise, RSpec, etc.

##### README for missing details
- We infer: PostgreSQL (via `database.yml`), Puma (`config/puma.rb`), Redis or DB queue, AWS S3 storage, GitHub Actions for CI/CD.

- Clients: Web SPA, Mobile Apps, or third-party integrators
- API Layer: Load Balancer / API Gateway (AWS ALB/NGINX)
- Application Containers: Rails app running Puma in Docker (ECS Task)
- Relational Database: PostgreSQL (Amazon RDS)
- Object Storage: AWS S3 bucket (ActiveStorage)
- Background Job Processor: Separate ECS service or worker container (ActiveJob / DelayedJob)
- Email Service: External SMTP or AWS SES (ActionMailer)
- CI/CD: GitHub Actions workflows triggering Docker builds and ECS deployments

1. Client → HTTPS → Load Balancer → ECS Rails Container
2. Rails Container → SQL (read/write) → PostgreSQL RDS
3. Rails Container → S3 API → S3 Bucket (file uploads/downloads)
4. Rails Container (Auth) ↔ DeviseTokenAuth logic (in-process)
5. Rails Container → DB job enqueue → jobs table (ActiveJob)
6. Worker Container polls jobs table → executes background services → may send Email or write DB
7. Rails Container → SMTP/API → Email Service (confirmations, invites)
8. GitHub Actions → Docker build & push → ECS deploy

c. Architectural patterns & design principles:
- MVC at core, extended by service-objects (single-responsibility)
- Query Objects for encapsulating read logic (`app/queries/*`)
- Serializer layer (JSON:API–style) for response shaping
- API Versioning (v1) to support backward compatibility
- Layered hexagon: controllers → services → models → persistence
- Containerization & twelve-factor app principles (config via ENV, stateless pods)

d. Key technologies/frameworks (annotate each component):
- Ruby 3.x, Rails 7.x, Puma Web Server
- Docker, AWS ECS (Fargate or EC2 launch type)
- PostgreSQL (RDS)
- AWS S3 (via ActiveStorage)
- ActiveJob + DelayedJob (or custom queue adapter)
- ActionMailer + AWS SES/SMTP
- Devise + DeviseTokenAuth (authentication)
- GitHub Actions (CI/CD), Brakeman, RuboCop (quality checks)

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef clients fill:#cccccc,stroke:#333,stroke-width:1px
    classDef app fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef db fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef ext fill:#ffcc80,stroke:#333,stroke-width:1px

    subgraph "Clients"
        Web["Web SPA"]:::clients
        Mobile["Mobile App"]:::clients
        Third["Third-party Integrator"]:::clients
    end

    subgraph "AWS / Infrastructure"
        LB["Load Balancer / API Gateway\n(AWS ALB/NGINX)"]:::app

        subgraph "ECS Cluster"
            subgraph "Rails App (Docker/ECS)"
                RB["API Controllers (v1)"]:::app
                AuthCont["Auth Controllers"]:::app
                Routes["Routes"]:::app
                Svc["Service Objects"]:::app
                Qry["Query Objects"]:::app
                Ser["Serializers"]:::app
                Mod["Models"]:::app
                JobsDef["Enqueue Jobs (ActiveJob)"]:::app
                DBQueue["Job Schema"]:::app
                Mailcomp["Mailers"]:::app
                StorageConf["ActiveStorage Config"]:::app
                AuthConf["DeviseTokenAuth Config"]:::app
                GenInit["General Initializers"]:::app
                DBConf["Database Config"]:::app
                Migs["Migrations"]:::app
                Seeds["Seed Data"]:::app
                BootConf["App Boot Config"]:::app
                PumaConf["Puma Config"]:::app
            end

            subgraph "Worker (Docker/ECS)"
                Worker["Background Worker"]:::app
            end
        end

        RDS["PostgreSQL (RDS)"]:::db
        S3["AWS S3 Bucket"]:::db

        CI["GitHub Actions CI/CD"]:::ext
        Registry["Container Registry"]:::ext
        SMTP["Email Service (SES/SMTP)"]:::ext
    end

    Web -->|HTTPS| LB
    Mobile -->|HTTPS| LB
    Third -->|HTTPS| LB

    LB -->|API Request| RB

    RB -->|read/write| RDS
    Svc -->|read| RDS
    JobsDef -->|enqueue| RDS
    DBQueue -->|schema| RDS
    Worker -->|poll jobs| RDS

    RB -->|upload/download| S3

    RB -->|send email| SMTP
    Worker -->|send email| SMTP

    CI -->|build & push| Registry
    Registry -->|deploy| LB

    click RB "https://github.com/taira0222/juku-cloud-backend/tree/main/app/controllers/api/v1"
    click AuthCont "https://github.com/taira0222/juku-cloud-backend/tree/main/app/controllers/api/v1/auth"
    click Routes "https://github.com/taira0222/juku-cloud-backend/blob/main/config/routes.rb"
    click Svc "https://github.com/taira0222/juku-cloud-backend/tree/main/app/services"
    click Qry "https://github.com/taira0222/juku-cloud-backend/tree/main/app/queries"
    click Ser "https://github.com/taira0222/juku-cloud-backend/tree/main/app/serializers"
    click Mod "https://github.com/taira0222/juku-cloud-backend/tree/main/app/models"
    click JobsDef "https://github.com/taira0222/juku-cloud-backend/tree/main/app/jobs"
    click DBQueue "https://github.com/taira0222/juku-cloud-backend/blob/main/db/queue_schema.rb"
    click StorageConf "https://github.com/taira0222/juku-cloud-backend/blob/main/config/storage.yml"
    click Dockerfile "https://github.com/taira0222/juku-cloud-backend/tree/main/Dockerfile"
    click PumaConf "https://github.com/taira0222/juku-cloud-backend/blob/main/config/puma.rb"
    click ECSTask "https://github.com/taira0222/juku-cloud-backend/blob/main/ecs/taskdef.json"
    click AuthConf "https://github.com/taira0222/juku-cloud-backend/blob/main/config/initializers/devise_token_auth.rb"
    click GenInit "https://github.com/taira0222/juku-cloud-backend/tree/main/config/initializers"
    click DBConf "https://github.com/taira0222/juku-cloud-backend/blob/main/config/database.yml"
    click Migs "https://github.com/taira0222/juku-cloud-backend/tree/main/db/migrate"
    click Seeds "https://github.com/taira0222/juku-cloud-backend/tree/main/db/seed_data"
    click Mailcomp "https://github.com/taira0222/juku-cloud-backend/tree/main/app/mailers"
    click CI "https://github.com/taira0222/juku-cloud-backend/blob/main/.github/workflows/ci_cd.yml"
    click Gemfile "https://github.com/taira0222/juku-cloud-backend/tree/main/Gemfile"
    click BootConf "https://github.com/taira0222/juku-cloud-backend/blob/main/config/application.rb"

    class Web,Mobile,Third clients
    class LB,RB,AuthCont,Rt,Routes,Svc,Qry,Ser,Mod,JobsDef,DBQueue,Mailcomp,StorageConf,AuthConf,GenInit,DBConf,Migs,Seeds,BootConf,PumaConf,Worker app
    class RDS,S3 db
    class CI,Registry,SMTP ext
```
