# saulvo/build-a-storefront-backend-udacity architecture

> Architecture diagram of the GitHub repository saulvo/build-a-storefront-backend-udacity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saulvo/build-a-storefront-backend-udacity
- Repository: https://github.com/saulvo/build-a-storefront-backend-udacity

## Overview

##### Project Type & Purpose
- This is a standalone backend service (Node.js + TypeScript) providing a RESTful storefront API (products, users, orders).
- It uses a PostgreSQL database (via Docker / docker-compose), migrations, and includes automated tests and CI workflows.

##### File Structure
- Top-level “src/” – source code:
– server.ts: entry point, sets up HTTP server and routes
– handlers/ (controllers): one handler per resource (order.ts, product.ts, user.ts)
– models/ (data layer): ORM or query wrappers for each resource
– helper/ (utilities): auth token logic, shared helpers
– database.ts: DB‐connection configuration (driven by .env + database.json)
– ship/ (API‐spec or CLI‐task definitions)
- migrations/: DB schema evolution scripts (with SQL up/down files)
- tests/: unit/integration specs for handlers & models
- CI/CD: .github/workflows/manual.yml
- Config: .env example, tsconfig.json, package.json, docker-compose.yml

##### README Insights
- Describes environment setup, Docker for Postgres, migration commands (db-up), build & start scripts, test configuration.
- No frontend – clients interact via HTTP on port 3000.

##### Main Components
A. API Gateway / HTTP Server
– Node.js runtime (TypeScript) hosting an HTTP server (Express or built-in)
– Reads .env for PORT, DB credentials, TOKEN_SECRET
B. Handlers (Controllers)
– product, user, order handlers implementing REST endpoints (CRUD + login)
C. Business/Data Layer (Models)
– Models define queries against PostgreSQL, assemble domain objects
D. Helpers & Auth
– JWT token generation, request validation
E. Database
– PostgreSQL container (docker-compose)
– Manages storefront_products, storefront_users, storefront_orders, order_products tables
– Migration service to version schema
F. External Interfaces
– HTTP clients (web/mobile apps, Postman)
– CI/CD (GitHub Actions)
– “ship” scripts (CLI or API spec files)

##### Relationships & Data Flow
1. Client → HTTP Server (port 3000)
2. Server routes request → appropriate Handler
3. Handler invokes Models (through database.ts connection)
4. Models execute SQL → PostgreSQL
5. PostgreSQL returns data → Models → Handler → Response
6. Auth helper intercepts protected routes → verifies TOKEN_SECRET
7. Migrations service updates schema on startup (npm run db-up)
8. CI workflow builds, tests, and can (optionally) deploy

##### Architectural Patterns
- Layered Architecture (Controller → Service/Model → Data Store)
- Modular organization by domain (order, product, user)
- Configuration via environment and JSON files
- Automated schema migrations (up/down SQL files)
- Test suites organized by layer (handler-specs, model-specs)

##### Technologies & Frameworks
- Node.js + TypeScript
- PostgreSQL (Docker)
- Migration tool (custom SQL files)
- Testing: Jasmine (spec/support/jasmine.json)
- CI: GitHub Actions (.github/workflows)
- “ship” (custom CLI or API spec integration)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actors
    Clients["External Clients (Web/Mobile/Postman)"]:::external
    CI["CI/CD (GitHub Actions)"]:::external

    %% Runtime Components
    Server["HTTP Server (Node.js + TypeScript)"]:::runtime

    %% Configuration
    subgraph "Configuration" 
        EnvExample[".env.example"]:::config
        DBJson["database.json"]:::config
        DBConfig["DB Connection Module\n(src/database.ts)"]:::code
    end

    %% Handlers / Controllers
    subgraph "Handlers (Controllers)" 
        IndexHandler["Route Setup\n(src/handlers/index.ts)"]:::code
        ProductHandler["Product Handler\n(src/handlers/product.ts)"]:::code
        UserHandler["User Handler\n(src/handlers/user.ts)"]:::code
        OrderHandler["Order Handler\n(src/handlers/order.ts)"]:::code
    end

    %% Business/Data Layer
    subgraph "Models (Data Layer)"
        IndexModel["Models Index\n(src/models/index.ts)"]:::code
        ProductModel["Product Model\n(src/models/product.ts)"]:::code
        UserModel["User Model\n(src/models/user.ts)"]:::code
        OrderModel["Order Model\n(src/models/order.ts)"]:::code
    end

    %% Helpers & Auth
    subgraph "Helpers & Auth"
        AuthHelper["Auth Token Logic\n(src/helper/auth.ts)"]:::code
        Utils["Shared Utilities\n(src/helper/index.ts)"]:::code
    end

    %% Database and Migrations
    subgraph "Database & Migrations"
        Postgres[(PostgreSQL Database)]:::datastore
        Migrations["Migration Service\n(migrations/*.js)"]:::code
        SQLFiles["SQL Up/Down Files\n(migrations/sqls/*.sql)"]:::scripts
    end

    %% Ship Scripts
    subgraph "Ship CLI / API Specs"
        ShipRoot["src/ship"]:::code
        ShipEnv["env scripts\n(src/ship/env/test.lua)"]:::scripts
        ShipProduct["Product Specs\n(src/ship/product/*.ship)"]:::scripts
        ShipUser["User Specs\n(src/ship/users/*.ship)"]:::scripts
        ShipOrder["Order Specs\n(src/ship/order/*.ship)"]:::scripts
    end

    %% Tests
    subgraph "Automated Tests"
        HandlerSpecs["Handler Specs\n(src/tests/handler-specs/*.spec.ts)"]:::tests
        ModelSpecs["Model Specs\n(src/tests/model-specs/*.spec.ts)"]:::tests
        JasmineConfig["Jasmine Config\n(spec/support/jasmine.json)"]:::config
    end

    %% Docker
    DockerCompose["Docker Compose\n(docker-compose.yml)"]:::runtime

    %% TypeScript & Package
    TSConfig["tsconfig.json"]:::config
    PackageJson["package.json"]:::config

    %% Relationships
    Clients -->|"HTTP Request"| Server
    Server -->|"routes to"| IndexHandler
    IndexHandler -->|calls| ProductHandler
    IndexHandler -->|calls| UserHandler
    IndexHandler -->|calls| OrderHandler

    ProductHandler -->|"invoke"| ProductModel
    UserHandler -->|"invoke"| UserModel
    OrderHandler -->|"invoke"| OrderModel

    AuthHelper -->|verifies JWT| IndexHandler
    Utils -->|utility functions| ProductHandler
    Utils -->|utility functions| UserHandler
    Utils -->|utility functions| OrderHandler

    ProductModel -->|"SQL queries"| Postgres
    UserModel -->|"SQL queries"| Postgres
    OrderModel -->|"SQL queries"| Postgres

    Migrations -->|applies schema| Postgres
    SQLFiles -->|definitions| Migrations

    CI -->|runs| HandlerSpecs
    CI -->|runs| ModelSpecs
    CI -->|uses| JasmineConfig
    CI -->|triggers migrations| Migrations

    DockerCompose -->|launches| Postgres

    EnvExample -->|provides env vars| Server
    DBJson -->|provides DB config| DBConfig
    DBConfig -->|connection| ProductModel
    DBConfig -->|connection| UserModel
    DBConfig -->|connection| OrderModel

    ShipRoot -->|defines CLI| Server
    ShipEnv -->|script| ShipRoot
    ShipProduct -->|spec| ShipRoot
    ShipUser -->|spec| ShipRoot
    ShipOrder -->|spec| ShipRoot

    TSConfig -->|TypeScript setup| Server
    PackageJson -->|metadata/scripts| Server

    CI -->|uses| DockerCompose

    %% Click Events
    click Server "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/server.ts"
    click EnvExample "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/.env.example"
    click DBJson "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/database.json"
    click DBConfig "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/database.ts"
    click ProductHandler "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/handlers/product.ts"
    click UserHandler "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/handlers/user.ts"
    click OrderHandler "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/handlers/order.ts"
    click IndexHandler "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/handlers/index.ts"
    click ProductModel "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/models/product.ts"
    click UserModel "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/models/user.ts"
    click OrderModel "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/models/order.ts"
    click IndexModel "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/models/index.ts"
    click AuthHelper "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/helper/auth.ts"
    click Utils "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/helper/index.ts"
    click Migrations "https://github.com/saulvo/build-a-storefront-backend-udacity/tree/master/migrations"
    click SQLFiles "https://github.com/saulvo/build-a-storefront-backend-udacity/tree/master/migrations/sqls"
    click ShipRoot "https://github.com/saulvo/build-a-storefront-backend-udacity/tree/master/src/ship"
    click ShipEnv "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/src/ship/env/test.lua"
    click ShipProduct "https://github.com/saulvo/build-a-storefront-backend-udacity/tree/master/src/ship/product"
    click ShipUser "https://github.com/saulvo/build-a-storefront-backend-udacity/tree/master/src/ship/users"
    click ShipOrder "https://github.com/saulvo/build-a-storefront-backend-udacity/tree/master/src/ship/order"
    click HandlerSpecs "https://github.com/saulvo/build-a-storefront-backend-udacity/tree/master/src/tests/handler-specs"
    click ModelSpecs "https://github.com/saulvo/build-a-storefront-backend-udacity/tree/master/src/tests/model-specs"
    click JasmineConfig "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/spec/support/jasmine.json"
    click CI "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/.github/workflows/manual.yml"
    click DockerCompose "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/docker-compose.yml"
    click TSConfig "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/tsconfig.json"
    click PackageJson "https://github.com/saulvo/build-a-storefront-backend-udacity/blob/master/package.json"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef runtime fill:#DFFFE0,stroke:#28A745,color:#28A745
    classDef datastore fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef external fill:#E0E0E0,stroke:#A0A0A0,color:#555555
    classDef config fill:#F5F5F5,stroke:#CCCCCC,color:#333333
    classDef scripts fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A
    classDef tests fill:#E1F5FE,stroke:#039BE5,color:#0277BD
```
