# peregrinno/rika-backend architecture

> Architecture diagram of the GitHub repository peregrinno/rika-backend, 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/peregrinno/rika-backend
- Repository: https://github.com/peregrinno/rika-backend

## Overview

##### Project Type and Purpose
- This is a RESTful authentication API (“Rika App”) built with Ruby + Sinatra, using JWT for stateless auth and PostgreSQL for persistence.
- It exposes endpoints for user registration, login, and protected resources (e.g., “cycle” endpoints).

##### High-Level File Structure Analysis
- Top-level entrypoints:
- app.rb + config.ru → boots the Sinatra app
- .env(.example) → runtime configuration (DB, JWT secret, CORS)
- Gemfile → declares Ruby dependencies (Sinatra, ActiveRecord, JWT, BCrypt, etc.)
- src/ → main application code
- config/ → DB connections & ActiveRecord setup
- routes/ → HTTP routing definitions (auth_routes, cycle_routes, central router)
- middlewares/ → request‐handling middleware (auth_middleware for JWT validation)
- controllers/ → action handlers (AuthController, CycleController, BaseController)
- services/ → domain services (TokenService, MailerService)
- contracts/ → input/schema validation (AuthContract, CycleContract)
- models/ → ActiveRecord models (User, Cycle)
- lib/ → shared utilities (API response formatting, CORS headers, validation helpers)
- Rakefile + migrations → database lifecycle (create, migrate, rollback)

##### Key Components
a. Clients
- Web/mobile front-end or any HTTP client
b. API Gateway / Web Server
- `app.rb` / Sinatra → handles incoming HTTP requests
c. Routing Layer
- `src/routes/router.rb` orchestrates `auth_routes` & `cycle_routes`
d. Middleware
- `src/middlewares/auth_middleware.rb` → verifies JWT, rejects unauthorized requests
e. Controllers
- `AuthController` → register/login
- `CycleController` → protected resource operations
f. Validation Layer
- `AuthContract`, `CycleContract` → enforce request schemas before business logic
g. Services
- `TokenService` → generate & verify JWT tokens
- `MailerService` → send confirmation or notification emails
h. Models & Database
- ActiveRecord models (`User`, `Cycle`) → map to PostgreSQL tables
- Database (PostgreSQL) → persistent store
i. Utilities
- CORS headers injector, API response formatting, error handlers

##### Component Interactions & Data Flow
1. Client issues HTTP request → hits Sinatra server (`app.rb`)
2. Request flows through `AuthMiddleware` (if endpoint protected)
3. Router delegates to specific controller
4. Controller invokes Contract for payload validation
5. On success: Controller calls Service(s) or Model(s)
- TokenService for login → signs JWT
- MailerService for welcome emails
- Models read/write data via ActiveRecord → DB
6. Controller packs data into a standardized API response (via `ApiResponse`)
7. Response returns to client

##### Architectural Patterns & Principles
- Layered Architecture: clear separation (Routing → Middleware → Controllers → Services → Models → DB)
- Stateless Authentication: JWT tokens passed on each request
- Single-responsibility: each component has one concern (validation vs. business logic vs. persistence)
- Configuration via environment variables for 12-factor compliance

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["HTTP Client\n(Web/Mobile)"]:::external
    Env["Env Config\n(.env.example)"]:::external
    Gem["Dependencies\n(Gemfile)"]:::external
    GemLock["Gemfile.lock"]:::external

    app["Sinatra Server\n(app.rb\nconfig.ru)"]:::http

    DBConfigFile["DB Config\n(database.yml)"]:::data
    DBConfigRB["DB Config\n(database.rb)"]:::data

    Router["Router\n(src/routes/router.rb)"]:::http
    AuthRoutes["Auth Routes\n(src/routes/auth_routes.rb)"]:::http
    CycleRoutes["Cycle Routes\n(src/routes/cycle_routes.rb)"]:::http

    Middleware["Auth Middleware\n(src/middlewares/auth_middleware.rb)"]:::http

    BaseCtrl["BaseController\n(src/controllers/base_controller.rb)"]:::business
    AuthCtrl["AuthController\n(src/controllers/auth_controller.rb)"]:::business
    CycleCtrl["CycleController\n(src/controllers/cycle_controller.rb)"]:::business

    AuthContract["AuthContract\n(src/contracts/auth_contract.rb)"]:::business
    CycleContract["CycleContract\n(src/contracts/cycle_contract.rb)"]:::business

    TokenService["TokenService\n(src/services/token_service.rb)"]:::business
    MailerService["MailerService\n(src/services/mailer_service.rb)"]:::business

    UserModel["User Model\n(src/models/user.rb)"]:::data
    CycleModel["Cycle Model\n(src/models/cycle.rb)"]:::data
    DB["PostgreSQL\n(Database)"]:::data

    ApiResponse["API Response Formatter\n(src/lib/api_response.rb)"]:::data
    CORS["CORS Injector\n(src/lib/cors_headers.rb)"]:::data
    HTTPHelper["HTTP Helpers\n(src/lib/http_response.rb)"]:::data
    ValidationHelper["Validation Helpers\n(src/lib/validation.rb)"]:::data

    SMTP["SMTP Service\n(External)"]:::external

    Rake["Rake Tasks\n(src/Rakefile)"]:::data

    Client -->|HTTP/JSON| app
    app --> Env
    app --> Gem
    app --> GemLock
    app --> DBConfigFile
    app --> DBConfigRB

    app --> Router

    Router --> AuthRoutes
    Router --> CycleRoutes

    AuthRoutes --> Middleware
    CycleRoutes --> Middleware

    Middleware --> AuthCtrl
    Middleware --> CycleCtrl

    AuthRoutes --> AuthCtrl

    AuthCtrl --> AuthContract
    AuthCtrl --> TokenService
    AuthCtrl --> MailerService
    AuthCtrl --> UserModel
    AuthCtrl --> ApiResponse

    CycleRoutes --> CycleCtrl
    CycleCtrl --> CycleContract
    CycleCtrl --> CycleModel
    CycleCtrl --> ApiResponse

    TokenService --> SMTP
    UserModel --> DB
    CycleModel --> DB
    ApiResponse --> app

    classDef http fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef business fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px

    click app "https://github.com/peregrinno/rika-backend/blob/main/app.rb"
    click app "https://github.com/peregrinno/rika-backend/blob/main/config.ru"
    click Env "https://github.com/peregrinno/rika-backend/blob/main/.env.example"
    click Gem "https://github.com/peregrinno/rika-backend/tree/main/Gemfile"
    click GemLock "https://github.com/peregrinno/rika-backend/blob/main/Gemfile.lock"
    click DBConfigFile "https://github.com/peregrinno/rika-backend/blob/main/src/config/database.yml"
    click DBConfigRB "https://github.com/peregrinno/rika-backend/blob/main/src/config/database.rb"
    click Router "https://github.com/peregrinno/rika-backend/blob/main/src/routes/router.rb"
    click AuthRoutes "https://github.com/peregrinno/rika-backend/blob/main/src/routes/auth_routes.rb"
    click CycleRoutes "https://github.com/peregrinno/rika-backend/blob/main/src/routes/cycle_routes.rb"
    click Middleware "https://github.com/peregrinno/rika-backend/blob/main/src/middlewares/auth_middleware.rb"
    click BaseCtrl "https://github.com/peregrinno/rika-backend/blob/main/src/controllers/base_controller.rb"
    click AuthCtrl "https://github.com/peregrinno/rika-backend/blob/main/src/controllers/auth_controller.rb"
    click CycleCtrl "https://github.com/peregrinno/rika-backend/blob/main/src/controllers/cycle_controller.rb"
    click AuthContract "https://github.com/peregrinno/rika-backend/blob/main/src/contracts/auth_contract.rb"
    click CycleContract "https://github.com/peregrinno/rika-backend/blob/main/src/contracts/cycle_contract.rb"
    click TokenService "https://github.com/peregrinno/rika-backend/blob/main/src/services/token_service.rb"
    click MailerService "https://github.com/peregrinno/rika-backend/blob/main/src/services/mailer_service.rb"
    click UserModel "https://github.com/peregrinno/rika-backend/blob/main/src/models/user.rb"
    click CycleModel "https://github.com/peregrinno/rika-backend/blob/main/src/models/cycle.rb"
    click ApiResponse "https://github.com/peregrinno/rika-backend/blob/main/src/lib/api_response.rb"
    click CORS "https://github.com/peregrinno/rika-backend/blob/main/src/lib/cors_headers.rb"
    click HTTPHelper "https://github.com/peregrinno/rika-backend/blob/main/src/lib/http_response.rb"
    click ValidationHelper "https://github.com/peregrinno/rika-backend/blob/main/src/lib/validation.rb"
    click Rake "https://github.com/peregrinno/rika-backend/tree/main/src/Rakefile"
```
