# illenko/banking-onboarding architecture

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

- Interactive diagram: https://gitdiagram.com/illenko/banking-onboarding
- Repository: https://github.com/illenko/banking-onboarding

## Overview

##### Main Components
- Environment/Infrastructure: Represent the “environment” directory which includes Docker Compose and dynamic configuration files. This covers infrastructure services such as the Temporal server, databases, and any other containerized infrastructure required to run the system locally.
- Onboarding Service: This service (in the “onboarding-service” directory) exposes the HTTP API that accepts requests from client applications. It is responsible for starting onboarding processes and interacting with the underlying Temporal workflows.
- Onboarding Worker: Found in “onboarding-worker”, this service runs worker processes that pick up and process workflow tasks, executing the actual business logic defined in the onboarding flow.
- Onboarding Common Library: The “onboarding-common” directory contains shared code such as workflows, activities (like antifraud checks, user creation, agreement generation, etc.), configuration, queues, and data models. This common package underpins both the service and worker.
- Stub Service: Lastly, the “stub-service” simulates external or downstream services (e.g., for external banking interactions) and should be demonstrated as a separate component.

##### Relationships and Interactions
- The Client (or external caller) sends onboarding requests to the Onboarding Service’s API.
- The Onboarding Service, using the common library, initiates a Temporal workflow that manages the multi-step process (antifraud checks, account creation, agreement generation, signature validation, etc.).
- The Onboarding Worker executes the activities defined by the workflow (using code from “onboarding-common”) and processes signals (e.g., when the client submits an agreement signature).
- The Stub Service is invoked to simulate or replace calls to external system components, perhaps during the various steps that would normally reach out to other services.
- All components and configurations required for local development/testing are provided through the infrastructure (Docker Compose, environment variables, etc.).

##### Architectural Patterns/Design Principles
- Microservices: Components are split between API and worker services with clear separation of responsibilities.
- Workflow-based Processing: Temporal orchestrates the long-running onboarding workflow, and the common library abstracts the workflow and related activities.
- Shared Code and Modularity: The common package (“onboarding-common”) encapsulates reusable logic that both services rely on.
- Containerization and Configuration: The “environment” directory ensures that services run in isolated containers configured through Docker Compose.

##### Main Elements
- Environment/Infrastructure (Docker Compose, Temporal server, and supporting services).
- Onboarding Service (exposing HTTP endpoints, handling client API calls).
- Onboarding Worker (processing asynchronous workflow tasks).
- Onboarding Common Library (depicted as shared or embedded within both the Service and Worker components).
- Stub Service (for simulating external integrations).

- Data flow from the client to the Onboarding Service.
- Communication from the Onboarding Service to the Temporal engine (initiating workflows defined in the common library).
- Workflow task delegation from Temporal to the Onboarding Worker.
- Outbound calls from both the Service/Worker (as applicable) to the Stub Service to simulate interactions with external systems.
- Feedback loops or signals (especially the signature validation step where the service might wait for a client-provided signature/signal).

- “Onboarding Service (HTTP API)” – listens for requests, returns responses (and onboarding PDF links).
- “Onboarding Worker (Temporal Worker)” – executes workflow steps (antifraud, user/account creation, etc.).
- “Onboarding Common” – shared workflow logic and constants.
- “Infrastructure/Environment” – contains configuration for local deployment (Docker compose, .env, etc.).
- “Stub Service” – simulates third-party integrations.

- Rectangles for services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("Client (External Caller)"):::client
    INF["Infrastructure (Docker Compose, .env, Configuration)"]:::infra
    IS["Onboarding Service (HTTP API) - Gin"]:::service
    TWE(("Temporal Workflow Engine (Temporal)")):::temporal
    OW["Onboarding Worker (Temporal Worker)"]:::service
    OC["Onboarding Common Library"]:::library
    SS["Stub Service"]:::service

    Client -->|"sends request"| IS
    INF -->|"configures"| IS
    INF -->|"configures"| TWE
    INF -->|"configures"| OW
    IS -->|"initiates workflow"| TWE
    TWE -->|"assigns tasks"| OW
    IS -->|"uses shared"| OC
    OW -->|"uses shared"| OC
    IS -->|"calls stub"| SS
    OW -->|"calls stub"| SS

    click INF "https://github.com/illenko/banking-onboarding/tree/main/environment/"
    click IS "https://github.com/illenko/banking-onboarding/tree/main/onboarding-service/"
    click OW "https://github.com/illenko/banking-onboarding/tree/main/onboarding-worker/"
    click OC "https://github.com/illenko/banking-onboarding/tree/main/onboarding-common/"
    click SS "https://github.com/illenko/banking-onboarding/tree/main/stub-service/"

    classDef client fill:#a2d9ce,stroke:#333,stroke-width:2px;
    classDef service fill:#f7dc6f,stroke:#333,stroke-width:2px;
    classDef infra fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef library fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef temporal fill:#f9e79f,stroke:#333,stroke-width:2px;
```
