# feedhenry-raincatcher/raincatcher-server architecture

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

- Interactive diagram: https://gitdiagram.com/feedhenry-raincatcher/raincatcher-server
- Repository: https://github.com/feedhenry-raincatcher/raincatcher-server

## Overview

##### Project type and purpose
- This is a server-side, full-stack Node.js/TypeScript cloud application (part of the RainCatcher suite).
- It exposes HTTP endpoints, serves a small UI (Handlebars templates + CSS), and provides data-sync, authentication, and session management.

##### Main components
a. Client (Frontend)
- Static assets (public/style.css)
- Handlebars views (views/login.hbs)
- User’s browser sends HTTP requests to the server UI and APIs.
b. Node.js Server (Express)
- Entry point: application.js (compiled from src/app.ts)
- Configuration tier: config-dev.js / config-prod.js
- Routing layer:
– src/user-routes (HTTP route definitions)
- Business modules:
– datasync (Connector.ts → connects to data-sync API, uses MongoDataHandler.ts)
– session (RedisSession.ts → session store)
– authentication
- passport-auth (local/demo user repository)
- keycloak (OIDC integration)
– wfm-user (static user repository)
- Utility: Config.ts for env/config loading
c. Data Stores / External Services
- MongoDB (accessed by MongoDataHandler)
- Redis (session storage)
- Keycloak server (external identity provider)
d. Development & Build
- TypeScript compiler (tsconfig.json → transpiles src/*.ts to .js + .map)
- nodemon.json for live-reload

##### Component relationships & data flows
- Within Express Server, show flows:
1. Static-file middleware → public/ + views/
2. Routing → user-routes → controllers
3. Controller → invokes business module (e.g., datasync, auth, session)
- Authentication flow:
- Browser → “/login” → passport-auth or Keycloak → RedisSession → success → session cookie
- Data sync flow:
- API request → datasync/Connector → MongoDataHandler → MongoDB
- datasync filters apply (e.g., ExcludeCompletedWorkorders)
- Session flow: Express middleware reads/writes session data in Redis.

##### Architectural patterns & design principles
- Layered architecture:
- Presentation → Routing → Business logic → Data access
- Modular design: each feature lives in src/modules/<feature>
- Externalized configuration: config files per environment
- Use of standard middleware (Express, Passport, Keycloak OIDC)

##### Final checklist
- [ ] A container node labeled “Browser / Client”
- [ ] A container node labeled “Node.js / Express Server”
– Routing (user-routes)
– Business modules (datasync, session, auth, wfm-user)
– Utility / Config loader
- [ ] External data stores: MongoDB, Redis
- [ ] External Auth service: Keycloak
- HTTP requests (client → server → modules → DB / service)
- Session reads/writes (server ↔ Redis)
- Data sync operations (server ↔ MongoDB)
- Auth flows (server ↔ Keycloak)
- [ ] Environment/config notes (config-dev.js vs config-prod.js)

Use this structure as your blueprint. It captures every essential architectural element without overthinking—simply group into logical components and show how data and control flow between them.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Browser / Client" 
        direction TB
        Client["User Browser"]:::client
    end

    Client -->|"HTTP GET/POST"| Server["Node.js / Express Server"]:::server

    %% Server Container
    subgraph "Node.js / Express Server"
        direction TB
        entryJS["application.js"]:::config
        entryTS["src/app.ts"]:::config

        subgraph "Configuration Tier"
            direction TB
            configDev["config-dev.js"]:::config
            configProd["config-prod.js"]:::config
        end

        subgraph "Routing Layer"
            direction TB
            userRoutesSrc["src/user-routes/index.ts"]:::module
            userRoutesJS["src/user-routes/index.js"]:::module
        end

        subgraph "Static Serving"
            direction TB
            StaticAssets["public/style.css"]:::client
            Views["views/login.hbs"]:::client
        end

        subgraph "Business Modules"
            direction TB
            subgraph "DataSync Module"
                direction TB
                ConnectorTS["src/modules/datasync/Connector.ts"]:::module
                ConnectorJS["src/modules/datasync/Connector.js"]:::module
                MongoHandlerTS["src/modules/datasync/MongoDataHandler.ts"]:::module
                MongoHandlerJS["src/modules/datasync/MongoDataHandler.js"]:::module
                Filters["src/modules/datasync/filters/ExcludeCompletedWorkorders.ts"]:::module
            end
            subgraph "Session Module"
                direction TB
                RedisSessionTS["src/modules/session/RedisSession.ts"]:::module
                RedisSessionJS["src/modules/session/RedisSession.js"]:::module
            end
            subgraph "Authentication"
                direction TB
                PassportRepoTS["src/modules/passport-auth/DemoUserRepository.ts"]:::module
                PassportRepoJS["src/modules/passport-auth/DemoUserRepository.js"]:::module
                PassportIndexTS["src/modules/passport-auth/index.ts"]:::module
                PassportIndexJS["src/modules/passport-auth/index.js"]:::module
                UsersData["src/modules/passport-auth/users.json"]:::module
                KeycloakTS["src/modules/keycloak/index.ts"]:::module
                KeycloakJS["src/modules/keycloak/index.js"]:::module
            end
            subgraph "WFM User Module"
                direction TB
                WFMRepoTS["src/modules/wfm-user/StaticUsersRepository.ts"]:::module
                WFMRepoJS["src/modules/wfm-user/StaticUsersRepository.js"]:::module
                WFMData["src/modules/wfm-user/users.json"]:::module
            end
        end

        subgraph "Utility"
            direction TB
            ConfigTS["src/util/Config.ts"]:::module
            ConfigJS["src/util/Config.js"]:::module
        end

        %% Development & Build
        subgraph "Development & Build"
            direction TB
            TSConfig["tsconfig.json"]:::build
            Nodemon["nodemon.json"]:::build
        end
    end

    %% External Data Stores & Services
    MongoDB["MongoDB"]:::db
    RedisDB["Redis"]:::db
    KeycloakExt["Keycloak"]:::external

    %% Internal Flows
    Server --> entryJS
    Server --> entryTS
    entryJS --> configDev
    entryJS --> configProd
    Server --> StaticAssets
    Server --> Views
    Server --> userRoutesSrc
    userRoutesSrc --> userRoutesJS

    userRoutesJS --> ConnectorJS
    userRoutesJS --> RedisSessionJS
    userRoutesJS --> PassportIndexJS
    userRoutesJS --> KeycloakJS

    ConnectorJS --> MongoHandlerJS
    ConnectorJS --> Filters
    MongoHandlerJS --> MongoDB

    RedisSessionJS <--> RedisDB

    PassportIndexJS --> PassportRepoJS
    PassportIndexJS --> UsersData
    PassportIndexJS --> RedisSessionJS

    KeycloakJS --> KeycloakExt
    KeycloakJS --> RedisSessionJS

    PassportIndexJS --> WFMRepoJS
    WFMRepoJS --> WFMData

    Server --> ConfigTS
    ConfigTS --> ConfigJS

    %% Build Tools
    Server --> TSConfig
    Server --> Nodemon

    %% Click Events
    click StaticAssets "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/public/style.css"
    click Views "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/views/login.hbs"
    click entryJS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/application.js"
    click entryTS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/app.ts"
    click configDev "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/config-dev.js"
    click configProd "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/config-prod.js"
    click TSConfig "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/tsconfig.json"
    click Nodemon "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/nodemon.json"
    click userRoutesSrc "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/user-routes/index.ts"
    click userRoutesJS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/user-routes/index.js"
    click ConnectorTS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/datasync/Connector.ts"
    click ConnectorJS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/datasync/Connector.js"
    click MongoHandlerTS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/datasync/MongoDataHandler.ts"
    click MongoHandlerJS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/datasync/MongoDataHandler.js"
    click Filters "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/datasync/filters/ExcludeCompletedWorkorders.ts"
    click RedisSessionTS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/session/RedisSession.ts"
    click RedisSessionJS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/session/RedisSession.js"
    click PassportRepoTS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/passport-auth/DemoUserRepository.ts"
    click PassportRepoJS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/passport-auth/DemoUserRepository.js"
    click PassportIndexTS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/passport-auth/index.ts"
    click PassportIndexJS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/passport-auth/index.js"
    click UsersData "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/passport-auth/users.json"
    click KeycloakTS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/keycloak/index.ts"
    click KeycloakJS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/keycloak/index.js"
    click WFMRepoTS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/wfm-user/StaticUsersRepository.ts"
    click WFMRepoJS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/wfm-user/StaticUsersRepository.js"
    click WFMData "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/modules/wfm-user/users.json"
    click ConfigTS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/util/Config.ts"
    click ConfigJS "https://github.com/feedhenry-raincatcher/raincatcher-server/blob/master/src/util/Config.js"

    %% Styles
    classDef client fill:#D6EAF8,stroke:#3498DB,color:#154360;
    classDef server fill:#FADBD8,stroke:#E74C3C,color:#641E16;
    classDef module fill:#D5F5E3,stroke:#27AE60,color:#145A32;
    classDef db fill:#FCF3CF,stroke:#F1C40F,color:#7D6608;
    classDef external fill:#E8DAEF,stroke:#8E44AD,color:#4A235A;
    classDef config fill:#EBDEF0,stroke:#9B59B6,color:#4A235A;
    classDef build fill:#FDEBD0,stroke:#F39C12,color:#7E5109;
```
