# foryoursafety/lostnfound-api architecture

> Architecture diagram of the GitHub repository foryoursafety/lostnfound-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/foryoursafety/lostnfound-api
- Repository: https://github.com/foryoursafety/lostnfound-api

## Overview

##### Project type and purpose
- This is a monolithic, backend‐only RESTful JSON API written in Ruby.
- It implements a “LostNFound” system: accounts can post items (lost or found) and contacts can be associated with those items.

##### Main components
a. Clients / Consumer
- Any HTTP client (e.g. web front‐end, mobile app, curl/Postman)
b. HTTP Server & Rack Layer
- Puma (the app server) receives HTTP requests
- Rack middleware (config.ru) hands requests off to the Ruby app
c. Controllers (app/controllers)
- account, auth, item, contact, and root controllers parse HTTP requests, invoke services, and serialize JSON responses
d. Service Layer (app/services)
- Business‐logic classes (e.g. CreateItemForOwner, AddTagToItem) orchestrate model and lib calls
e. Models & Persistence
- ORM-style model classes (app/models/*.rb) represent Accounts, Items, Contacts, Tags, Passwords
- app/lib/secure_db.rb abstracts encrypted DB access; key_stretch.rb handles password hashing
- DB migrations & seeds (db/migrations, db/seeds) define and populate the schema
f. Configuration & Secrets
- config/environments.rb and config/secrets.yml manage environment‐specific settings
g. Testing Suite (spec/)
- Unit and integration specs validate controllers, services, and lib modules

##### Relationships and data-flow
1. Client issues HTTP request →
2. Puma / Rack →
3. Controller (e.g. ItemsController#create) →
4. Service (e.g. CreateItemForOwner) →
5. Model / lib (e.g. Item.save via secure_db) →
6. Database (SQL)
7. Bubble response back up the chain, serialize JSON, return to Client

##### Architectural patterns & design principles
- MVC‐style layering: Controllers handle I/O, Services encapsulate use‐cases, Models encapsulate data.
- Single‐process monolith: no microservices, everything runs in one Ruby process.
- Clear separation of concerns: cryptography in app/lib, business logic in app/services.

##### Relevant technologies & frameworks
- Ruby (version in .ruby-version)
- Rack + config.ru + Puma
- Bundler/Gems indicated in Gemfile
- YAML for config & seeds
- Rake tasks for DB management & tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["HTTP Client"]:::external

    %% Runtime Layer
    Puma["Puma Server"]:::runtime
    RackLayer["Rack Layer\n(config.ru)"]:::runtime

    %% Controllers Layer
    subgraph "Controllers" 
        AccountsCtrl["AccountsController"]:::app
        AuthCtrl["AuthController"]:::app
        ItemsCtrl["ItemsController"]:::app
        ContactsRouter["Routes Entry\n(app/controllers/app.rb)"]:::app
        HttpRequestCtrl["HttpRequestController\n(app/controllers/http_request.rb)"]:::app
    end

    %% Services Layer
    subgraph "Services"
        CreateItem["CreateItemForOwner"]:::app
        AddTag["AddTagToItem"]:::app
        Authenticate["AuthenticateAccount"]:::app
        CreateContact["CreateContactForItem"]:::app
    end

    %% Models & Libs Layer
    subgraph "Models & Persistence"
        AccountModel["Account Model"]:::app
        ItemModel["Item Model"]:::app
        ContactModel["Contact Model"]:::app
        TagModel["Tag Model"]:::app
        PasswordModel["Password Model"]:::app
        SecureDB["SecureDB\n(app/lib/secure_db.rb)"]:::app
        KeyStretch["KeyStretch\n(app/lib/key_stretch.rb)"]:::app
        Migrations["DB Migrations\n(db/migrations/*.rb)"]:::app
        Seeds["DB Seeds\n(db/seeds/*.yml)"]:::app
    end

    %% Database
    DB["Database"]:::db

    %% Config & Secrets
    subgraph "Config & Secrets"
        Environments["Environments\n(config/environments.rb)"]:::app
        Secrets["Secrets Template\n(config/secrets-example.yml)"]:::app
    end

    %% Testing Suite
    subgraph "Testing Suite"
        SpecHelper["Spec Helper\n(spec/spec_helper.rb)"]:::test
        EnvSpec["Env Spec\n(spec/env_spec.rb)"]:::test
        UnitSpecs["Unit Specs\n(spec/unit/)"]:::test
        IntegrationSpecs["Integration Specs\n(spec/integration/)"]:::test
    end

    %% Project Metadata
    subgraph "Project Metadata"
        RubyVer[".ruby-version"]:::app
        Gemfile["Gemfile"]:::app
        GemfileLock["Gemfile.lock"]:::app
        Rakefile["Rakefile"]:::app
    end

    %% Data Flow
    Client -->|"HTTP Request"| Puma
    Puma -->|"forwards"| RackLayer
    RackLayer -->|"routes to"| AccountsCtrl
    RackLayer --> AuthCtrl
    RackLayer --> ItemsCtrl
    RackLayer --> ContactsRouter
    ContactsRouter --> HttpRequestCtrl

    AccountsCtrl -->|"calls"| Authenticate
    AuthCtrl --> Authenticate

    ItemsCtrl --> CreateItem
    ItemsCtrl --> AddTag
    ContactsRouter --> CreateContact
    HttpRequestCtrl --> CreateContact

    Authenticate --> AccountModel
    CreateItem --> ItemModel
    CreateItem --> SecureDB
    AddTag --> TagModel
    AddTag --> SecureDB
    CreateContact --> ContactModel
    CreateContact --> SecureDB

    AccountModel --> Migrations
    ItemModel --> Migrations
    ContactModel --> Migrations
    TagModel --> Migrations
    PasswordModel --> Migrations

    SecureDB --> KeyStretch
    SecureDB --> DB
    Migrations --> DB
    Seeds --> DB

    DB -->|"JSON Response"| AccountsCtrl
    DB --> AuthCtrl
    DB --> ItemsCtrl
    DB --> ContactsRouter

    %% Config & Secrets connections
    Environments --> RackLayer
    Secrets --> RackLayer

    %% Tests linked
    UnitSpecs --> AccountsCtrl
    UnitSpecs --> Services
    IntegrationSpecs --> RackLayer
    IntegrationSpecs --> DB

    SpecHelper --> UnitSpecs
    SpecHelper --> IntegrationSpecs
    EnvSpec --> RackLayer

    %% Project metadata influences
    RubyVer --> Puma
    Gemfile --> RackLayer
    GemfileLock --> RackLayer
    Rakefile --> Migrations
    Rakefile --> SpecHelper

    %% Click Events
    click RackLayer "https://github.com/foryoursafety/lostnfound-api/blob/main/config.ru"
    click AccountsCtrl "https://github.com/foryoursafety/lostnfound-api/blob/main/app/controllers/accounts.rb"
    click AuthCtrl "https://github.com/foryoursafety/lostnfound-api/blob/main/app/controllers/auth.rb"
    click ItemsCtrl "https://github.com/foryoursafety/lostnfound-api/blob/main/app/controllers/items.rb"
    click ContactsRouter "https://github.com/foryoursafety/lostnfound-api/blob/main/app/controllers/app.rb"
    click HttpRequestCtrl "https://github.com/foryoursafety/lostnfound-api/blob/main/app/controllers/http_request.rb"
    click CreateItem "https://github.com/foryoursafety/lostnfound-api/blob/main/app/services/create_item_for_owner.rb"
    click AddTag "https://github.com/foryoursafety/lostnfound-api/blob/main/app/services/add_tag_to_item.rb"
    click Authenticate "https://github.com/foryoursafety/lostnfound-api/blob/main/app/services/authenticate_account.rb"
    click CreateContact "https://github.com/foryoursafety/lostnfound-api/blob/main/app/services/create_contact_for_item.rb"
    click AccountModel "https://github.com/foryoursafety/lostnfound-api/blob/main/app/models/account.rb"
    click ItemModel "https://github.com/foryoursafety/lostnfound-api/blob/main/app/models/item.rb"
    click ContactModel "https://github.com/foryoursafety/lostnfound-api/blob/main/app/models/contact.rb"
    click TagModel "https://github.com/foryoursafety/lostnfound-api/blob/main/app/models/tag.rb"
    click PasswordModel "https://github.com/foryoursafety/lostnfound-api/blob/main/app/models/password.rb"
    click SecureDB "https://github.com/foryoursafety/lostnfound-api/blob/main/app/lib/secure_db.rb"
    click KeyStretch "https://github.com/foryoursafety/lostnfound-api/blob/main/app/lib/key_stretch.rb"
    click Migrations "https://github.com/foryoursafety/lostnfound-api/tree/main/db/migrations/"
    click Seeds "https://github.com/foryoursafety/lostnfound-api/tree/main/db/seeds/"
    click Environments "https://github.com/foryoursafety/lostnfound-api/blob/main/config/environments.rb"
    click Secrets "https://github.com/foryoursafety/lostnfound-api/blob/main/config/secrets-example.yml"
    click SpecHelper "https://github.com/foryoursafety/lostnfound-api/blob/main/spec/spec_helper.rb"
    click EnvSpec "https://github.com/foryoursafety/lostnfound-api/blob/main/spec/env_spec.rb"
    click UnitSpecs "https://github.com/foryoursafety/lostnfound-api/tree/main/spec/unit/"
    click IntegrationSpecs "https://github.com/foryoursafety/lostnfound-api/tree/main/spec/integration/"
    click RubyVer "https://github.com/foryoursafety/lostnfound-api/blob/main/.ruby-version"
    click Gemfile "https://github.com/foryoursafety/lostnfound-api/tree/main/Gemfile"
    click GemfileLock "https://github.com/foryoursafety/lostnfound-api/blob/main/Gemfile.lock"
    click Rakefile "https://github.com/foryoursafety/lostnfound-api/tree/main/Rakefile"

    %% Styles
    classDef external fill:#D5F5E3,stroke:#27AE60
    classDef runtime fill:#AED6F1,stroke:#2980B9
    classDef app fill:#F9E79F,stroke:#D4AC0D
    classDef db fill:#BDC3C7,stroke:#7F8C8D
    classDef test fill:#F5B7B1,stroke:#C0392B
```
