# amano216/minori architecture

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

- Interactive diagram: https://gitdiagram.com/amano216/minori
- Repository: https://github.com/amano216/minori

## Overview

##### Project Type and Purpose
- This is a full-stack web application composed of a Ruby on Rails 7 API backend and a React/TypeScript SPA frontend.
- It targets home-visit nursing (“訪問看護”) agencies, providing an integrated contract/signature management, user/office administration, and reporting system.

##### File Structure Analysis
- Top-level services (in docker-compose.yml):
- web (Rails API)
- frontend (esbuild watch)
- css (Tailwind watch)
- Backend
- app/controllers/api/v1: RESTful JWT-protected endpoints
- app/models / app/repositories: ActiveRecord + repository pattern
- app/services: business logic (PDF generation, JWT service, contract workflows)
- app/domains: domain–driven design with events, value objects, domain services
- app/jobs & app/mailers: background processing & emails
- config/storage.yml: ActiveStorage adapters (local/S3)
- config/cable.yml & app/channels: WebSocket (ActionCable) support
- Frontend
- app/javascript: React components, pages, hooks, Zustand stores
- api client modules under app/javascript/api
- Tailwind CSS for styling, esbuild for bundling
- Infrastructure
- PostgreSQL (primary data store)
- Redis (caching, job queue/Siderkiq support, token cleanup)
- Docker Compose orchestrates web, js, css services
- Sidekiq (implied by background jobs/cron docs)

##### Key Architectural Patterns
- API-First separation: React SPA communicates via /api/v1 over JWT
- Domain-Driven Design: app/domains split by subdomains (office, user, contract), with domain events
- Repository and Service layers to decouple ActiveRecord from business logic
- Background jobs (ActionMailer, cleanup, metrics) via Sidekiq
- Pundit for authorization policies

##### Components
a. Client Layer
- Browser (React SPA)
- Static assets served by Rails (or separate CDN)
b. API Layer
- Rails API containers:
- Controllers → ApplicationController → Api::V1 namespace
- Authentication: Devise + JWTService → token lifecycle endpoints
- Authorization: Pundit policies
c. Domain & Persistence
- Domain modules (business rules, events)
- Repository layer → ActiveRecord models → PostgreSQL
- ActiveStorage → file/PDF attachments → S3 or local disk
d. Background Processing
- Sidekiq queue (Redis)
- Jobs for email, token cleanup, PDF gen
e. Real-time
- ActionCable WebSocket server → Redis pub/sub
f. Infrastructure
- Docker Compose (web, frontend, css)
- PostgreSQL database
- Redis instance
- External email service (SMTP)

##### Relationships & Data Flow
1) User in browser loads React SPA
2) SPA calls /api/v1 endpoints (login, contracts, offices, signature requests)
3) Rails API authenticates (JWT), authorizes (Pundit), routes to controllers
4) Controller invokes service/repository/domain layers
5) Data persisted to PostgreSQL; domain events dispatched
6) File uploads → ActiveStorage → bucket
7) Background jobs enqueued in Redis → Sidekiq processes (email, cleanup, metrics)
8) ActionCable pushes real-time updates (e.g. signature completion)

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Client Layer"
    React["React SPA"]:::client
    Components["UI Components & Pages"]:::client
    APIMod["API Client Modules"]:::client
    Stores["Zustand Stores"]:::client
    Styles["Tailwind CSS"]:::client
  end

  subgraph "API Layer"
    Controllers["Rails Controllers (Api::V1)"]:::api
    AuthCtrl["Auth Controller & JWT Service"]:::api
    Policies["Pundit Policies"]:::api
  end

  subgraph "Domain & Persistence"
    Domain["Domain Models (DDD)"]:::api
    Repos["Repository Layer"]:::api
    Models["ActiveRecord Models"]:::db
    Services["Business Logic Services"]:::api
    StorageCfg["ActiveStorage Config"]:::api
    DB["PostgreSQL"]:::db
  end

  subgraph "Background Processing"
    Jobs["Sidekiq Workers"]:::background
    Cleanup["Token Cleanup Jobs"]:::background
    Mailers["Mailers"]:::background
  end

  subgraph "Real-time"
    Channels["ActionCable Channels"]:::background
    CableCfg["Cable Config"]:::background
    RedisPub["Redis Pub/Sub"]:::queue
  end

  subgraph "Infrastructure"
    Docker["Docker Compose"]:::infra
    Redis["Redis"]:::queue
    S3["S3 Bucket"]:::db
    SMTP["External SMTP"]:::ext
  end

  %% Client interactions
  React -->|"REST /api/v1"| Controllers
  React -->|"imports"| APIMod
  React -->|"uses"| Stores
  React -->|"styles"| Styles

  %% API Layer flows
  Controllers -->|"auth & token"| AuthCtrl
  Controllers -->|"authorize"| Policies
  Controllers -->|"invoke domain"| Domain
  Controllers -->|"use services"| Services
  Controllers -->|"query"| Repos

  %% Persistence flows
  Domain -->|"business rules"| Repos
  Repos -->|"SQL"| Models
  Models -->|"persist"| DB
  Controllers -->|"SQL"| DB
  StorageCfg -->|"store files"| S3
  Controllers -->|"file upload"| StorageCfg

  %% Background jobs
  Controllers -->|"enqueue (Redis)"| Redis
  Redis -->|"jobs queue"| Jobs
  Jobs -->|"db updates"| DB
  Jobs -->|"send email"| SMTP
  Jobs -->|"cache cleanup"| Redis

  %% Real-time
  Controllers -->|"WebSocket"| Channels
  Channels -->|"pub/sub"| RedisPub
  Channels -->|"push updates"| React

  %% Infrastructure orchestration
  Docker --> React
  Docker --> Controllers
  Docker --> Styles
  Docker --> Redis
  Docker --> DB

  %% Click Events
  click React "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/javascript"
  click Components "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/javascript/components"
  click Components "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/javascript/pages"
  click APIMod "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/javascript/api"
  click Stores "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/javascript/stores"
  click Styles "https://github.com/amano216/minori/blob/feature/office-domain-phase2/tailwind.config.js"
  click Controllers "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/controllers/api/v1"
  click AuthCtrl "https://github.com/amano216/minori/blob/feature/office-domain-phase2/app/controllers/api/v1/auth_controller.rb"
  click AuthCtrl "https://github.com/amano216/minori/blob/feature/office-domain-phase2/app/services/jwt_service.rb"
  click Policies "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/policies"
  click Domain "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/domains"
  click Repos "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/repositories"
  click Models "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/models"
  click Services "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/services"
  click StorageCfg "https://github.com/amano216/minori/blob/feature/office-domain-phase2/config/storage.yml"
  click Jobs "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/jobs"
  click Cleanup "https://github.com/amano216/minori/blob/feature/office-domain-phase2/app/jobs/cleanup_expired_tokens_job.rb"
  click Cleanup "https://github.com/amano216/minori/blob/feature/office-domain-phase2/app/jobs/jwt_cleanup_job.rb"
  click Cleanup "https://github.com/amano216/minori/blob/feature/office-domain-phase2/app/jobs/refresh_token_cleanup_job.rb"
  click Mailers "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/mailers"
  click Channels "https://github.com/amano216/minori/tree/feature/office-domain-phase2/app/channels"
  click CableCfg "https://github.com/amano216/minori/blob/feature/office-domain-phase2/config/cable.yml"
  click Docker "https://github.com/amano216/minori/blob/feature/office-domain-phase2/docker-compose.yml"

  %% Styles
  classDef client fill:#D6E9FE,stroke:#0366D6,color:#0366D6
  classDef api fill:#DFF0D8,stroke:#3C763D,color:#3C763D
  classDef db fill:#F2DEDE,stroke:#A94442,color:#A94442
  classDef background fill:#FCF8E3,stroke:#8A6D3B,color:#8A6D3B
  classDef queue fill:#EEEFF8,stroke:#5A5A9E,color:#5A5A9E
  classDef infra fill:#F5F5F5,stroke:#333333,color:#333333
  classDef ext fill:#E0E0E0,stroke:#666,color:#666
```
