# trademebooks/trademebooks-web architecture

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

- Interactive diagram: https://gitdiagram.com/trademebooks/trademebooks-web
- Repository: https://github.com/trademebooks/trademebooks-web

## Overview

##### Project Type and Purpose
- This is a full-stack, single-page web application called trademebooks.com (TMB).
- Frontend: React/Redux SPA served from the Node.js server (or CDN in production).
- Backend: Node.js + Express REST API implementing domain-driven layers (controllers, services, repositories).
- Database: MongoDB (Atlas).
- External Services: OAuth providers (Facebook, Google, GitHub, LinkedIn, Twitter), SendGrid (email), Twilio (SMS).
- Deployment: Heroku, with CI/CD via CircleCI and GitHub Actions.

##### File Structure Highlights
- Top-level “client” and “api” folders separate frontend and backend.
- “api”:
- config: environment configuration, passport OAuth strategies.
- controllers ↔ routes: Express endpoints calling controllers.
- domain: DDD layers – models (Mongoose schemas), repositories (DB access), services (business logic), events, DTOs.
- middleware: auth, permissions, global handlers.
- utils: error handling, DB connection.
- tests & seeds: automated tests and seed scripts.
- “client”:
- src/components: React components organized by feature (auth, books, chat, account, UI layout).
- src/actions, src/reducers, src/store.js: Redux data flow.
- src/config: client env config.
- src/utils/api.js: centralized API client.
- setupProxy.js: local CORS/proxy config.
- tests co-located with components.

##### Key Insights from README
- Emphasizes social SSO, profile/bookstore, chat/messaging, auto-complete book metadata.
- Tech stack: ReactJS, Redux, Node.js, Express, MongoDB, Passport.js, SendGrid, Twilio, Heroku.
- Dev flow: local dev server on :3000 proxying API on :5000; Docker option for Mongo; CI with linting, tests, auto-deploy on master.

##### Components
a. Client-side (React/Redux SPA)
- UI Components (Pages, Forms, Chat UI, Bookstore pages)
- Redux Store & Thunks / Actions
- API Client (axios/fetch layer)
b. Server-side (Express API)
- HTTP Layer: Routes → Controllers
- Domain Layer: Controllers → Services → Repositories → MongoDB
- Middleware: Authentication, Authorization, Validation, Error Handling
- Passport.js (multiple OAuth strategies)
c. Database
- MongoDB Atlas cluster (collections: users, books, bookstores, chats, messages, sessions, passwords)
d. External Services
- OAuth Providers (Facebook, Google, GitHub, LinkedIn, Twitter)
- SendGrid (email templates: registration, password reset)
- Twilio (SMS notifications)
e. Infrastructure & DevOps
- Heroku (web dyno, environment configs)
- CI/CD: CircleCI & GitHub Actions
- Monitoring: Uptime Robot, Codecov

##### Relationships & Data Flows
- Browser → (HTTPS) → React App (served by Express or CDN)
- React Components dispatch Redux Actions → async API calls via api.js → Express REST Endpoints (e.g., POST /api/v1/auth/login)
- Express middleware (auth, validation) → Controllers
- Controller invokes Domain Service → Repository → MongoDB
- Domain Service may emit Events (e.g., userRegistered) → trigger email/SMS services
- External OAuth redirects: Browser ↔ OAuth Provider ↔ Express callback route → create session/JWT
- SendGrid/Twilio usage: Service layer calls external API

##### Architectural Patterns & Principles
- Layered architecture (HTTP → Controller → Service → Repository → DB)
- DDD (domain models, DTOs, events)
- Single-Page Application + API backend
- Externalization of cross-cutting concerns via middleware
- Feature-based modularization on client side
- CI/CD and environment-based configuration

2. Client on the left, Server in the center (top to bottom: HTTP, Controllers, Services, Repositories), DB on the right, External services above/below the Server.
6. Review with domain experts to ensure every significant module (e.g., passport strategies, DTOs, event bus) is represented.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Frontend)"
        UI["UI Components"]:::frontend
        Store["Redux Store & Actions"]:::frontend
        APIClient["API Client (api.js)"]:::frontend
        Proxy["Proxy Config (setupProxy.js)"]:::frontend
    end

    %% Server Layer
    subgraph "Server (Backend)"
        Config["Env & Passport Config"]:::backend
        Routes["Express Routes"]:::backend
        Middleware["Middleware (Auth, Permissions, Errors)"]:::backend
        Controllers["Controllers"]:::backend
        Services["Domain Services"]:::backend
        Repos["Repositories"]:::backend
        Models["Domain Models"]:::backend
        DTOReq["DTOs (requests)"]:::backend
        DTORes["DTOs (responses)"]:::backend
        Events["Domain Events"]:::backend
        UtilsDB["DB Connection Utility"]:::backend
        UtilsErr["Global Error Handling Utils"]:::backend
        UtilsSSL["Heroku SSL Redirect"]:::backend
    end

    %% Database
    DB["MongoDB Atlas"]:::database

    %% External Services
    External["OAuth Providers"]:::external
    SendGrid["SendGrid Email Service"]:::external
    Twilio["Twilio SMS Service"]:::external

    %% Infrastructure
    Infra["Heroku & CI/CD & Monitoring"]:::infra

    %% Data Flows
    UI --> Store
    Store --> APIClient
    Proxy --> APIClient
    APIClient --> Routes
    Routes --> Middleware
    Middleware --> Controllers
    Controllers --> Services
    Services --> Repos
    Repos --> DB
    Controllers --> DTOReq
    Controllers --> DTORes
    Controllers --> Models
    Services --> Events
    Events --> SendGrid
    Events --> Twilio
    External --> Routes
    Routes --> External
    Config --> Middleware
    UtilsDB --> Repos
    UtilsErr --> Middleware
    UtilsSSL --> Middleware
    Infra --- Routes

    %% Click Events
    click UI "https://github.com/trademebooks/trademebooks-web/tree/master/client/src/components/"
    click Store "https://github.com/trademebooks/trademebooks-web/blob/master/client/src/store.js"
    click Store "https://github.com/trademebooks/trademebooks-web/tree/master/client/src/actions/"
    click APIClient "https://github.com/trademebooks/trademebooks-web/blob/master/client/src/utils/api.js"
    click Proxy "https://github.com/trademebooks/trademebooks-web/blob/master/client/src/setupProxy.js"
    click Routes "https://github.com/trademebooks/trademebooks-web/tree/master/api/routes/"
    click Controllers "https://github.com/trademebooks/trademebooks-web/tree/master/api/controllers/"
    click Models "https://github.com/trademebooks/trademebooks-web/tree/master/api/domain/models/"
    click Repos "https://github.com/trademebooks/trademebooks-web/tree/master/api/domain/repositories/"
    click Services "https://github.com/trademebooks/trademebooks-web/tree/master/api/domain/services/"
    click DTOReq "https://github.com/trademebooks/trademebooks-web/tree/master/api/dtos/requests/"
    click DTORes "https://github.com/trademebooks/trademebooks-web/tree/master/api/dtos/responses/"
    click Events "https://github.com/trademebooks/trademebooks-web/tree/master/api/events/"
    click Middleware "https://github.com/trademebooks/trademebooks-web/tree/master/api/middleware/"
    click Config "https://github.com/trademebooks/trademebooks-web/blob/master/api/config/index.js"
    click UtilsDB "https://github.com/trademebooks/trademebooks-web/blob/master/api/utils/db.js"
    click UtilsErr "https://github.com/trademebooks/trademebooks-web/blob/master/api/utils/globalExceptionHandler.js"
    click UtilsSSL "https://github.com/trademebooks/trademebooks-web/blob/master/api/utils/heroku-ssl-redirect.js"
    click SendGrid "https://github.com/trademebooks/trademebooks-web/blob/master/api/domain/services/mailer/email.sendgrid.service.js"
    click Twilio "https://github.com/trademebooks/trademebooks-web/blob/master/api/domain/services/sms.service.js"
    click Infra "https://github.com/trademebooks/trademebooks-web/blob/master/.circleci/config.yml"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef backend  fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef database fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
    classDef infra    fill:#ECEFF1,stroke:#455A64,color:#455A64
```
