# joinreinvest/reinvest-api architecture

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

- Interactive diagram: https://gitdiagram.com/joinreinvest/reinvest-api
- Repository: https://github.com/joinreinvest/reinvest-api

## Overview

##### Project Type and Purpose
- Recognize that this is a full-fledged API backend serving a sophisticated investment platform.
- It integrates many independent modules (each behaving like a microservice) with their own databases/migrations and communication channels.
- The API gateways (AdminApiGateway and ApiGateway) are the main entry points, and additional responsibilities (identity management, archiving, notifications, etc.) are housed in dedicated modules.
- Serverless functions and AWS integrations (e.g., Cognito for identity, SNS for notifications, Lambda functions for preSignUp, postSignUp, cron jobs, etc.) form an important part of the infrastructure.

##### Analyzing the File Structure
- Notice the top-level “Reinvest” folder that contains modules such as AdminApiGateway, ApiGateway, Archiving, Documents, Identity, InvestmentAccounts, Investments, LegalEntities, Notifications, Portfolio, Registration, Trading, etc. Each of these modules adheres to a consistent structure (migrations, src, and tests).
- Each module is isolated and usually has its own “infrastructure” (database adapters, repository implementations), “domain” (business rules and entities), and “application” (use case implementations).

a. Main Components:
- API Entry Points:
- API Gateway (GraphQL) and Admin API Gateway.
- Serverless functions (organized under devops/functions) serving as individual entry points for operations like preSignUp, postSignUp, cron jobs for sync and document generation, etc.
- Modules (each a microservice):
- Archiving, Documents, Identity, Inbox, InvestmentAccounts, Investments, LegalEntities, Notifications, Portfolio, Registration, Trading, SharesAndDividends, Verification, Withdrawals.
- Databases:
- Each module maintains its own PostgreSQL database (as signified by individual migrations and database adapters).
- External Services:
- AWS services: Cognito for user identity and authentication, SNS for notifications, S3 for file/document storage, VPC, SES for emails.
- Shared Infrastructure and Libraries:
- Shared libraries in the “shared” folder for logging, PostgreSQL connections, templates, and simple aggregator patterns.
- Client Interaction:
- Clients (Postman, API explorer) interact with the API gateways.

b. Relationships and Data Flow:
- Serverless functions as separate nodes that handle specific hooks (pre/post sign-up, cron jobs, migration operations) that assist in keeping financial operations, notifications, and synchronization tasks up-to-date.
- Relationship between the modules and the AWS environment (mentioning Cognito, S3, SNS, and Lambda) as well as CI/CD elements (e.g., GitHub workflows, serverless deployment commands).

c. Architectural Patterns:
- Clean Architecture / Hexagonal architecture pattern used in each module (with separation among domain, application, and infrastructure layers).
- Microservice/multi-module approach. Although not “share-everything,” modules communicate with each other via APIs and sometimes use queues or event handlers (for example, event-driven design is visible in the ‘EventHandler’ directories).
- Important role of dependency injection (hinted by the “getClassName” and “Module” interface definitions) and how modules are registered together in the system bootstrap.

d. Relevant Technologies and Frameworks:
- Node.js ecosystem with TypeScript.
- PostgreSQL driven by migrations in each module.
- AWS tools and serverless deployment (Cognito, Lambda, S3, SNS, CloudFormation/VPC).
- Docker Compose for local development.
- CI/CD processes using GitHub Actions, as indicated by the workflow files.
- GraphQL for the API gateways.
- Shared libraries indicate custom implementations for logging, PostgreSQL operations, and templating.

##### Summary Procedure for the Principal Software Engineer
- Serverless functions as separate nodes (with periodic tasks and hooks) that interact with both the API layer and the modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Client and API Gateways
    Client["Client (Postman/API Explorer)"]:::entry
    APIAdmin["Admin API Gateway"]:::entry
    APIPublic["API Gateway (Public)"]:::entry
    ServerlessFunc["Serverless Functions (Hooks, Cron, etc.)"]:::serverless

    Client --> APIAdmin
    Client --> APIPublic
    APIAdmin --> ServerlessFunc
    APIPublic --> ServerlessFunc

    %% Route to Modules from API Gateways
    APIAdmin --> ArchDomain
    APIPublic --> ArchDomain
    APIAdmin --> DocDomain
    APIPublic --> DocDomain
    APIAdmin --> IdDomain
    APIPublic --> IdDomain
    APIAdmin --> IbDomain
    APIPublic --> IbDomain
    APIAdmin --> InvAccDomain
    APIPublic --> InvAccDomain
    APIAdmin --> InvstDomain
    APIPublic --> InvstDomain
    APIAdmin --> LegEntDomain
    APIPublic --> LegEntDomain
    APIAdmin --> NotifDomain
    APIPublic --> NotifDomain
    APIAdmin --> PortfDomain
    APIPublic --> PortfDomain
    APIAdmin --> RegDomain
    APIPublic --> RegDomain
    APIAdmin --> SADDomain
    APIPublic --> SADDomain
    APIAdmin --> TradDomain
    APIPublic --> TradDomain
    APIAdmin --> VerDomain
    APIPublic --> VerDomain
    APIAdmin --> WithDomain
    APIPublic --> WithDomain

    %% Modules: Each module is broken down into layered components
    subgraph "Archiving Module"
        ArchDomain["Archiving Domain"]:::moduleDomain
        ArchApp["Archiving Application"]:::moduleApp
        ArchInfra["Archiving Infrastructure"]:::moduleInfra
        ArchDB["Archiving DB"]:::database
        ArchDomain --> ArchApp --> ArchInfra --> ArchDB
    end

    subgraph "Documents Module"
        DocDomain["Documents Domain"]:::moduleDomain
        DocApp["Documents Application"]:::moduleApp
        DocInfra["Documents Infrastructure"]:::moduleInfra
        DocDB["Documents DB"]:::database
        DocDomain --> DocApp --> DocInfra --> DocDB
    end

    subgraph "Identity Module"
        IdDomain["Identity Domain"]:::moduleDomain
        IdApp["Identity Application"]:::moduleApp
        IdInfra["Identity Infrastructure"]:::moduleInfra
        IdDB["Identity DB"]:::database
        IdDomain --> IdApp --> IdInfra --> IdDB
    end

    subgraph "Inbox Module"
        IbDomain["Inbox Domain"]:::moduleDomain
        IbApp["Inbox Application"]:::moduleApp
        IbInfra["Inbox Infrastructure"]:::moduleInfra
        IbDB["Inbox DB"]:::database
        IbDomain --> IbApp --> IbInfra --> IbDB
    end

    subgraph "InvestmentAccounts Module"
        InvAccDomain["InvestmentAccounts Domain"]:::moduleDomain
        InvAccApp["InvestmentAccounts Application"]:::moduleApp
        InvAccInfra["InvestmentAccounts Infrastructure"]:::moduleInfra
        InvAccDB["InvestmentAccounts DB"]:::database
        InvAccDomain --> InvAccApp --> InvAccInfra --> InvAccDB
    end

    subgraph "Investments Module"
        InvstDomain["Investments Domain"]:::moduleDomain
        InvstApp["Investments Application"]:::moduleApp
        InvstInfra["Investments Infrastructure"]:::moduleInfra
        InvstDB["Investments DB"]:::database
        InvstDomain --> InvstApp --> InvstInfra --> InvstDB
    end

    subgraph "LegalEntities Module"
        LegEntDomain["LegalEntities Domain"]:::moduleDomain
        LegEntApp["LegalEntities Application"]:::moduleApp
        LegEntInfra["LegalEntities Infrastructure"]:::moduleInfra
        LegEntDB["LegalEntities DB"]:::database
        LegEntDomain --> LegEntApp --> LegEntInfra --> LegEntDB
    end

    subgraph "Notifications Module"
        NotifDomain["Notifications Domain"]:::moduleDomain
        NotifApp["Notifications Application"]:::moduleApp
        NotifInfra["Notifications Infrastructure"]:::moduleInfra
        NotifDB["Notifications DB"]:::database
        NotifDomain --> NotifApp --> NotifInfra --> NotifDB
    end

    subgraph "Portfolio Module"
        PortfDomain["Portfolio Domain"]:::moduleDomain
        PortfApp["Portfolio Application"]:::moduleApp
        PortfInfra["Portfolio Infrastructure"]:::moduleInfra
        PortfDB["Portfolio DB"]:::database
        PortfDomain --> PortfApp --> PortfInfra --> PortfDB
    end

    subgraph "Registration Module"
        RegDomain["Registration Domain"]:::moduleDomain
        RegApp["Registration Application"]:::moduleApp
        RegInfra["Registration Infrastructure"]:::moduleInfra
        RegDB["Registration DB"]:::database
        RegDomain --> RegApp --> RegInfra --> RegDB
    end

    subgraph "SharesAndDividends Module"
        SADDomain["SharesAndDividends Domain"]:::moduleDomain
        SADApp["SharesAndDividends Application"]:::moduleApp
        SADInfra["SharesAndDividends Infrastructure"]:::moduleInfra
        SADDB["SharesAndDividends DB"]:::database
        SADDomain --> SADApp --> SADInfra --> SADDB
    end

    subgraph "Trading Module"
        TradDomain["Trading Domain"]:::moduleDomain
        TradApp["Trading Application"]:::moduleApp
        TradInfra["Trading Infrastructure"]:::moduleInfra
        TradDB["Trading DB"]:::database
        TradDomain --> TradApp --> TradInfra --> TradDB
    end

    subgraph "Verification Module"
        VerDomain["Verification Domain"]:::moduleDomain
        VerApp["Verification Application"]:::moduleApp
        VerInfra["Verification Infrastructure"]:::moduleInfra
        VerDB["Verification DB"]:::database
        VerDomain --> VerApp --> VerInfra --> VerDB
    end

    subgraph "Withdrawals Module"
        WithDomain["Withdrawals Domain"]:::moduleDomain
        WithApp["Withdrawals Application"]:::moduleApp
        WithInfra["Withdrawals Infrastructure"]:::moduleInfra
        WithDB["Withdrawals DB"]:::database
        WithDomain --> WithApp --> WithInfra --> WithDB
    end

    %% Inter-Service Communication Example
    InvstDomain ---|"communicates"| TradDomain

    %% Connections to External Systems & Shared Infrastructure
    ServerlessFunc --> AWSServices
    ServerlessFunc --> SharedLib

    AWSServices["AWS Services (Cognito, SNS, S3, SES, VPC)"]:::external
    SharedLib["Shared Libraries (Logging, PostgreSQL, Templates)"]:::shared

    %% Click Events
    click APIAdmin "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/AdminApiGateway"
    click APIPublic "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/ApiGateway"
    click ServerlessFunc "https://github.com/joinreinvest/reinvest-api/tree/development/devops/functions"
    click ArchDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Archiving"
    click DocDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Documents"
    click IdDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Identity"
    click IbDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Inbox"
    click InvAccDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/InvestmentAccounts"
    click InvstDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Investments"
    click LegEntDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/LegalEntities"
    click NotifDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Notifications"
    click PortfDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Portfolio"
    click RegDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Registration"
    click SADDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/SharesAndDividends"
    click TradDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Trading"
    click VerDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Verification"
    click WithDomain "https://github.com/joinreinvest/reinvest-api/tree/development/Reinvest/Withdrawals"
    click AWSServices "https://github.com/joinreinvest/reinvest-api/tree/development/devops/serverless"
    click SharedLib "https://github.com/joinreinvest/reinvest-api/tree/development/shared"

    %% Styles
    classDef entry fill:#fff2cc,stroke:#b58900,stroke-width:2px;
    classDef serverless fill:#d0f0c0,stroke:#2e8b57,stroke-width:2px;
    classDef moduleDomain fill:#cce5ff,stroke:#31708f,stroke-width:2px;
    classDef moduleApp fill:#e6f2ff,stroke:#31708f,stroke-width:2px;
    classDef moduleInfra fill:#f0f7ff,stroke:#31708f,stroke-width:2px;
    classDef database fill:#ffd1dc,stroke:#d6336c,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef shared fill:#e6e6ff,stroke:#3333cc,stroke-width:2px;
```
