# naro-tw/dfans-api architecture

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

- Interactive diagram: https://gitdiagram.com/naro-tw/dfans-api
- Repository: https://github.com/naro-tw/dfans-api

## Overview

##### Project type and purpose
- This is a standalone backend web API written in Ruby (using Rack, likely Sinatra or a custom controller framework).
- Purpose: manage confidential photo albums—create accounts, authenticate via tokens or SSO, create albums, upload/retrieve photos, enforce authorization policies.

##### File structure
- Top-level files: Gemfile (Ruby dependencies), Rakefile (task runner), config.ru (Rack launcher), Procfile (for Heroku-like deployment).
- app/controllers: HTTP entry points for each resource (accounts, albums, photos, auth), plus a central app.rb that wires routes.
- app/models: domain objects (Account, Album, Photo, Password, GithubAccount).
- app/services: business logic units (authentication, authorization, CRUD operations, participant management).
- app/policies: authorization rules and scopes.
- app/lib: supporting utilities (token generation, key stretching, JSON parsing, secure DB wrappers).
- app/db: migrations, seed data, and a “store” directory for persisted photo files.
- spec: integration and unit tests validating API contracts, services, and utilities.

##### README for additional insights
- The README lists RESTful JSON routes under `/api/v1`.
- Workflow: client → HTTP router → controller → service layer → model/DB → response.
- Supports external GitHub SSO (“authorize_sso” service).

##### Elements
- Clear labels: “Client”, “API Router”, each Controller, Service classes, Policy classes, Model/DB, File Store, External SSO.
- HTTP → Controller
- Controller → Service
- Service → Policy/Model/DB/Store
- Service → External SSO
- Model ↔ DB
- Front-end clients in blue
- API/web layer in green
- Business logic in yellow
- Data/storage in orange
- External services in gray

##### Detailed capture of essential elements
- Utilities (e.g., AuthToken generator, KeyStretch) next to the Service or Policy layer.
- Performance/security notes: e.g., key stretching slows brute-force, secure_db encrypts at rest.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client (Web/Mobile)"]:::frontend

    %% API Gateway / Router
    Router["API Router\n(config.ru → app/controllers/app.rb)"]:::web

    %% Controllers Layer
    subgraph "Controllers Layer"
        style Controllers fill:#e8f5e9,stroke:#2e7d32
        AccountsC["AccountsController"]:::web
        AlbumsC["AlbumsController"]:::web
        PhotosC["PhotosController"]:::web
        AuthC["AuthController"]:::web
        Helpers["Controller Helpers"]:::web
    end

    %% Service Layer
    subgraph "Service Layer"
        style Services fill:#fff8e1,stroke:#f9a825
        AuthA["AuthenticateAccount"]:::business
        AuthZ["AuthorizeAccount"]:::business
        AuthSSO["AuthorizeSso"]:::business
        VerifyReg["VerifyRegistration"]:::business
        CreateAlb["CreateAlbumForOwner"]:::business
        CreatePhoto["CreatePhoto"]:::business
        AddPart["AddParticipant"]:::business
        RemovePart["RemoveParticipant"]:::business
        GetAccQ["GetAccountQuery"]:::business
        GetAlbQ["GetAlbumQuery"]:::business
        GetPhotoQ["GetPhotoQuery"]:::business
    end

    %% Policy Layer
    subgraph "Policy Layer"
        style Policies fill:#fff3e0,stroke:#fb8c00
        AccP["AccountPolicy"]:::business
        AlbP["AlbumPolicy"]:::business
        AlbScopes["AlbumScopes"]:::business
        PhotoP["PhotoPolicy"]:::business
        PartReqP["ParticipantRequestPolicy"]:::business
    end

    %% Data Layer
    subgraph "Data Layer"
        style Data fill:#e3f2fd,stroke:#1565c0
        AccountM["Account"]:::data
        AlbumM["Album"]:::data
        PhotoM["Photo"]:::data
        PasswordM["Password"]:::data
        GithubAccM["GithubAccount"]:::data
        DB["Relational DB\n(SQLite/Postgres)"]:::data
    end

    %% Storage
    FileStore["File Store\n(app/db/store)"]:::data

    %% External Services
    GitHubSSO["GitHub SSO (OAuth)"]:::external

    %% Configuration & Entry Points
    ProcfileNode["Procfile"]:::web
    EnvNode["Environment Settings"]:::web
    GemfileNode["Gemfile / Gemfile.lock"]:::web
    AppLoader["App Loader\n(require_app.rb)"]:::web

    %% Flow
    Client -->|"HTTPS JSON"| Router
    Router --> AccountsC
    Router --> AlbumsC
    Router --> PhotosC
    Router --> AuthC
    ControllersLayer[Controllers Layer] -->|uses| Helpers

    AccountsC -->|calls| AuthA
    AccountsC -->|calls| VerifyReg
    AuthC -->|calls| AuthZ
    AuthC -->|calls| AuthSSO
    AlbumsC -->|calls| CreateAlb
    AlbumsC -->|calls| AddPart
    AlbumsC -->|calls| RemovePart
    AlbumsC -->|calls| GetAlbQ
    PhotosC -->|calls| CreatePhoto
    PhotosC -->|calls| GetPhotoQ

    AuthA -->|checks| AccP
    AuthZ -->|checks| AccP
    AuthSSO -->|external call| GitHubSSO
    VerifyReg -->|writes| AccountM
    CreateAlb -->|checks| AlbP
    CreateAlb -->|writes| AlbumM
    AddPart -->|checks| PartReqP
    RemovePart -->|checks| PartReqP
    CreatePhoto -->|checks| PhotoP
    CreatePhoto -->|writes| PhotoM
    GetAccQ -->|reads| AccountM
    GetAlbQ -->|reads| AlbumM
    GetPhotoQ -->|reads| PhotoM

    AccountM -->|migrates| DB
    AlbumM -->|migrates| DB
    PhotoM -->|migrates| DB
    PasswordM -->|migrates| DB
    GithubAccM -->|migrates| DB

    CreatePhoto -->|stores file| FileStore
    FileStore -->|metadata| DB

    %% Configuration dependencies
    Router --> AppLoader
    AppLoader --> EnvNode
    AppLoader --> GemfileNode
    ProcfileNode --> AppLoader

    %% Click Events
    click Router "https://github.com/naro-tw/dfans-api/blob/main/config.ru"
    click Router "https://github.com/naro-tw/dfans-api/blob/main/app/controllers/app.rb"
    click AccountsC "https://github.com/naro-tw/dfans-api/blob/main/app/controllers/accounts.rb"
    click AlbumsC "https://github.com/naro-tw/dfans-api/blob/main/app/controllers/albums.rb"
    click PhotosC "https://github.com/naro-tw/dfans-api/blob/main/app/controllers/photos.rb"
    click AuthC "https://github.com/naro-tw/dfans-api/blob/main/app/controllers/auth.rb"
    click Helpers "https://github.com/naro-tw/dfans-api/blob/main/app/controllers/helpers.rb"
    click AuthA "https://github.com/naro-tw/dfans-api/blob/main/app/services/authenticate_account.rb"
    click AuthZ "https://github.com/naro-tw/dfans-api/blob/main/app/services/authorize_account.rb"
    click AuthSSO "https://github.com/naro-tw/dfans-api/blob/main/app/services/authorize_sso.rb"
    click VerifyReg "https://github.com/naro-tw/dfans-api/blob/main/app/services/verify_registration.rb"
    click CreateAlb "https://github.com/naro-tw/dfans-api/blob/main/app/services/create_album_for_owner.rb"
    click CreatePhoto "https://github.com/naro-tw/dfans-api/blob/main/app/services/create_photo.rb"
    click AddPart "https://github.com/naro-tw/dfans-api/blob/main/app/services/add_participant.rb"
    click RemovePart "https://github.com/naro-tw/dfans-api/blob/main/app/services/remove_participant.rb"
    click GetAccQ "https://github.com/naro-tw/dfans-api/blob/main/app/services/get_account_query.rb"
    click GetAlbQ "https://github.com/naro-tw/dfans-api/blob/main/app/services/get_album_query.rb"
    click GetPhotoQ "https://github.com/naro-tw/dfans-api/blob/main/app/services/get_photo_query.rb"
    click AccP "https://github.com/naro-tw/dfans-api/blob/main/app/policies/account_policy.rb"
    click AlbP "https://github.com/naro-tw/dfans-api/blob/main/app/policies/album_policy.rb"
    click AlbScopes "https://github.com/naro-tw/dfans-api/blob/main/app/policies/album_scopes.rb"
    click PhotoP "https://github.com/naro-tw/dfans-api/blob/main/app/policies/photo_policy.rb"
    click PartReqP "https://github.com/naro-tw/dfans-api/blob/main/app/policies/participant_request_policy.rb"
    click AccountM "https://github.com/naro-tw/dfans-api/blob/main/app/models/account.rb"
    click AlbumM "https://github.com/naro-tw/dfans-api/blob/main/app/models/album.rb"
    click PhotoM "https://github.com/naro-tw/dfans-api/blob/main/app/models/photo.rb"
    click PasswordM "https://github.com/naro-tw/dfans-api/blob/main/app/models/password.rb"
    click GithubAccM "https://github.com/naro-tw/dfans-api/blob/main/app/models/github_account.rb"
    click FileStore "https://github.com/naro-tw/dfans-api/tree/main/app/db/store"
    click ProcfileNode "https://github.com/naro-tw/dfans-api/tree/main/Procfile"
    click EnvNode "https://github.com/naro-tw/dfans-api/blob/main/config/environments.rb"
    click AppLoader "https://github.com/naro-tw/dfans-api/blob/main/require_app.rb"
    click GemfileNode "https://github.com/naro-tw/dfans-api/tree/main/Gemfile"
    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef web fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32
    classDef business fill:#fff9c4,stroke:#f9a825,color:#f57f17
    classDef data fill:#ffe0b2,stroke:#ef6c00,color:#e65100
    classDef external fill:#eceff1,stroke:#607d8b,color:#37474f
```
