# sb10-part2-team2/sb10-hrbank-team2 architecture

> Architecture diagram of the GitHub repository sb10-part2-team2/sb10-hrbank-team2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sb10-part2-team2/sb10-hrbank-team2
- Repository: https://github.com/sb10-part2-team2/sb10-hrbank-team2

## Overview

Summary / project type and purpose
- This is a backend-focused RESTful Employee Management System ("HR Bank") implemented with Java + Spring Boot. It provides employee and department management APIs, advanced employee search (cursor-based pagination), a file management subsystem (metadata in DB + separate file storage), and a batch-based data backup system (Spring Scheduler). It targets deployment on Railway and uses PostgreSQL (prod) and H2 (local dev). Swagger (SpringDoc) exposes API docs.

How I derived this
- README describes features and shows a src/ main/java package layout with controller, service, repository, entity, dto, config packages — which indicates a layered Spring MVC architecture. README lists the tech stack (Spring Boot, JPA, MapStruct, Spring Scheduler, PostgreSQL/H2, SpringDoc, Railway).

- External actors and systems:
- API Consumers: Web UI, CLI, third-party services (or developers using Swagger UI).
- Railway (deployment platform) and managed Postgres / persistent volumes or external object storage (if used).
- Optional: Backup destination (cloud storage or Railway volume).

- Package structure to components. Components and relationships to show:
- REST API Layer (Controllers)
- EmployeeController
- DepartmentController
- BackupController
- Application / Business Logic Layer (Services)
- EmployeeService (search, cursor pagination, CRUD)
- DepartmentService
- FileService (stores metadata + files)
- BackupService (scheduled backups)
- Persistence Layer (Repositories)
- EmployeeRepository (JPA)
- DepartmentRepository
- FileMetadataRepository
- Domain Model
- Entities (Employee, Department, FileMetadata, BackupRecord)
- DTOs (mapped via MapStruct)
- Infrastructure / Integration
- Database (PostgreSQL / H2)
- File Storage (local filesystem, Railway persistent storage, or object store like S3 if integrated)
- Scheduler (Spring Scheduler)
- OpenAPI / Swagger (SpringDoc)
- Railway deployment / runtime
- Directional flows:
- HTTP request -> Controller -> Service -> Repository -> Database
- File upload: Controller -> FileService -> (persist metadata to DB + store file in File Storage)
- Backup scheduler: Scheduler triggers BackupService -> read DB and files -> write backup to Backup Storage
- DTO mapping: Service -> MapStruct -> DTO -> Controller -> HTTP response
- Important non-functional interactions like logging, health checks, and metrics if present or planned.

- Nodes:
- Railway App (application container/process) running Spring Boot
- PostgreSQL managed instance (Railway or external)
- File storage volume or Object Storage (S3, Railway persistent volume)
- CI/CD (GitHub Actions or pipeline, if used — README mentions GitHub but not CI; include as optional)
- Railway App ↔ PostgreSQL (JDBC)
- Railway App ↔ File storage (mount or API)
- Railway App ↔ External clients (HTTPS)
- Scheduler runs inside Railway App (Spring Scheduler thread)

- Controllers (explicitly list the three controllers shown in README)
- Service classes and major responsibilities (employee CRUD + search w/ cursor pagination; department management; file handling; backup)
- Repository layer (JPA interfaces)
- Entities and DTOs (show that DTOs are mapped from Entities using MapStruct)
- Database(s): show Postgres as primary, H2 for local dev (annotate as dev-only)
- API documentation endpoint: /swagger-ui/index.html (SpringDoc) — show as part of the app or as a developer-facing sub-component
- Config: application.yml (environment configuration), and config package (feature toggles, datasource config)
- Tests: test directory (note unit/integration tests exist but not shown in runtime)

Relationships and data flows to show clearly
- Request-response path: Client -> (HTTPS) -> Controller -> Service -> Repository -> DB -> Service -> Controller -> Client
- File upload flow: Client POST file -> EmployeeController or FileController -> FileService
- FileService splits: store binary in File Storage; write metadata record to FileMetadataRepository (DB). Include metadata fields (filename, type, size).
- Search flow with cursor pagination: Client -> EmployeeController -> EmployeeService -> EmployeeRepository (cursor-based query) -> return DTOs (via MapStruct) -> Client
- Backup flow: Spring Scheduler -> BackupService -> read DB and file storage -> store backup to Backup Storage / external archive
- Deployment interactions: Railway provides runtime environment; DB connections and file volumes configured via application.yml / Railway environment variables.

Architectural patterns and design principles used
- Layered architecture (Controller -> Service -> Repository) — classical Spring Boot MVC + service layer.
- Repository pattern via Spring Data JPA.
- DTO pattern + MapStruct for mapping between domain entities and external contract.
- Separation of concerns for file metadata vs. file binary storage (persistence vs. object storage).
- Scheduled batch jobs for backups (Spring Scheduler) — think of these as asynchronous system processes.
- Cursor-based pagination for efficient large-list traversal (stateless paging token vs offset).

- Language & framework: Java, Spring Boot
- Persistence: Spring Data JPA, PostgreSQL (prod), H2 (dev)
- Mapping: MapStruct
- API docs: SpringDoc OpenAPI (Swagger UI)
- Scheduling: Spring Scheduler (for batch backups)
- Hosting/Infra: Railway
- Supporting: application.yml config file(s), static resources location (static/)

- Rectangles for code components (controllers, services, repos)
- Controllers / API layer: blue
- Services / business logic: green
- Repositories / persistence interfaces: orange
- Datastores: purple
- File storage / object storage: brown/gray
- Small annotations beside components:
- Key classes or example filenames (e.g., EmployeeController.java, BackupController.java)
- Important endpoints (/employees, /departments, /backup, /swagger-ui/index.html)
- Cursor pagination mention for search flows

- Because this is backend-only (no dedicated frontend repo), emphasize API consumers (clients, Swagger UI) rather than a frontend app.
- Controllers explicitly (EmployeeController, DepartmentController, BackupController) — they are primary integration points.
- File handling as a two-part subsystem: metadata in DB + binary store separate — indicate where each lives.
- Batch scheduler and backup destination as first-class components — the README lists batch backups as a key feature.
- Distinguish production vs local dev setups:
- H2 as local-only and Postgres as production DB.
- Railway as the target deployment, with environment variables in application.yml controlling DB endpoints.

Practical diagramming tips

Essential elements checklist (must-haves)
- Clear labels for each component (use real class/package names where possible)
- Separate representation for DB vs file storage vs scheduler
- Dev vs prod differences (H2 vs Postgres)
- Swagger endpoint and hosting platform (Railway)
- DTO mapping and MapStruct usage between entities and API contracts
- Explicitly show cursor-based paging on the employee search flow

Closing note

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Context Diagram (high level)
    subgraph "Context Diagram" 
        direction TB
        API_Consumers["API Consumers<br/>(Web UI / CLI / 3rd-party / Developers)"]:::external
        HRBankApp["HR Bank Application<br/>(Spring Boot on Railway)"]:::app
        Railway["Railway (Hosting/Deployment)"]:::infra
        Postgres["PostgreSQL (prod)"]:::db
        H2["H2 (local-dev only)"]:::db_dev
        FileStore["File Storage / Persistent Volume<br/>(filesystem or object storage)"]:::filestorage
        BackupDest["Backup Destination<br/>(Cloud Storage or Railway Volume)"]:::backup
        SwaggerUI["Swagger UI<br/>(/swagger-ui/index.html)"]:::devtool

        API_Consumers -->|"HTTPS REST"| HRBankApp
        HRBankApp -->|"JDBC (read/write)"| Postgres
        HRBankApp -->|"JDBC (dev-only)"| H2
        HRBankApp -->|"Filesystem/API (store files)"| FileStore
        HRBankApp -->|"scheduled backups push"| BackupDest
        Railway -->|"hosts runtime & volumes"| HRBankApp
        HRBankApp -->|"developer docs"| SwaggerUI
    end

    %% Component Diagram (detailed internals)
    subgraph "Component Diagram" 
        direction TB

        %% API Layer
        subgraph "API Layer (Controllers)" 
            direction TB
            EmployeeController["EmployeeController<br/>(/employees)"]:::controller
            DepartmentController["DepartmentController<br/>(/departments)"]:::controller
            BackupController["BackupController<br/>(/backup)"]:::controller
        end

        %% Service Layer
        subgraph "Service Layer (Business Logic)" 
            direction TB
            EmployeeService["EmployeeService<br/>(CRUD,Search,CursorPagination)"]:::service
            DepartmentService["DepartmentService<br/>(CRUD)"]:::service
            FileService["FileService<br/>(store metadata+binary)"]:::service
            BackupService["BackupService<br/>(SpringScheduler jobs)"]:::service
        end

        %% Persistence Layer
        subgraph "Persistence Layer (Repositories)" 
            direction TB
            EmployeeRepo["EmployeeRepository<br/>(Spring Data JPA)"]:::repo
            DepartmentRepo["DepartmentRepository"]:::repo
            FileMetaRepo["FileMetadataRepository"]:::repo
        end

        %% Domain / Mapping
        subgraph "Domain Model & Mapping"
            direction TB
            Entities["Entities:<br/>Employee,Department,FileMetadata,BackupRecord"]:::domain
            DTOs["DTOs (MapStruct mapped)"]:::dto
            MapStruct["MapStruct (mapping layer)"]:::integration
        end

        %% Infrastructure / Integrations
        subgraph "Infrastructure & Integrations"
            direction TB
            Database["Database(s)"]:::dbgroup
            FileStorage["File Storage (separate from DB)"]:::filestorage
            Scheduler["Spring Scheduler (cron jobs)"]:::scheduler
            OpenAPI["SpringDoc OpenAPI (Swagger)"]:::devtool
            ConfigFiles["Config: application.yml / config package"]:::config
            LoggingMetrics["Logging / Health / Metrics"]:::infra
        end

        %% Connections between components (vertical flows)
        API_Layer[API_Layer_dummy]:::invis --> EmployeeController
        EmployeeController -->|"calls"| EmployeeService
        DepartmentController -->|"calls"| DepartmentService
        BackupController -->|"calls"| BackupService

        EmployeeService -->|"uses"| EmployeeRepo
        DepartmentService -->|"uses"| DepartmentRepo
        FileService -->|"writes metadata"| FileMetaRepo
        FileService -->|"stores binary"| FileStorage

        EmployeeService -->|"maps Entities↔DTOs via MapStruct"| MapStruct
        MapStruct -->|"transforms"| DTOs
        DTOs -->|"returned by controllers"| EmployeeController

        EmployeeRepo -->|"JPA queries (cursor pagination supported)"| Entities
        DepartmentRepo -->|"persists entities"| Entities
        FileMetaRepo -->|"persists metadata"| Entities

        BackupService -->|"reads DB and files"| EmployeeRepo
        BackupService -->|"reads files"| FileStorage
        BackupService -->|"writes backup"| BackupDest

        Scheduler -->|"triggers jobs"| BackupService
        OpenAPI -->|"exposes docs for"| API_Layer_dummy

        %% Annotations: endpoints and examples
        EmployeeController -.->|"endpoint: /employees"| EmployeeController
        DepartmentController -.->|"endpoint: /departments"| DepartmentController
        BackupController -.->|"endpoint: /backup (admin)"| BackupController

    end

    %% Deployment Diagram
    subgraph "Deployment Diagram"
        direction TB
        RailwayApp["Railway App Container<br/>(Spring Boot process)"]:::app
        ManagedPostgres["Managed PostgreSQL Instance"]:::db
        DevH2["H2 (embedded - local dev)"]:::db_dev
        PersistentVolume["Railway Persistent Volume / Mounted Filesystem"]:::filestorage
        ObjectStorage["Object Storage (S3-compatible) - optional"]:::filestorage
        CI_CD["CI / Repo (GitHub) & Optional CI Pipeline"]:::infra_optional

        API_Consumers2["External Clients (HTTPS)"]:::external

        API_Consumers2 -->|"HTTPS"| RailwayApp
        RailwayApp -->|"JDBC (env-configured)"| ManagedPostgres
        RailwayApp -->|"JDBC (dev-only)"| DevH2
        RailwayApp -->|"mount or API"| PersistentVolume
        RailwayApp -->|"optional API"| ObjectStorage
        RailwayApp -->|"runs Scheduler threads (cron)"| Scheduler
        CI_CD -->|"deploys to"| RailwayApp
    end

    %% Legend / Notes (stacked)
    subgraph "Legend & Notes"
        direction TB
        NoteShapes["Shapes: Rectangles=Components, Cylinders=Datastores, Rounded=External"]:::note
        NoteColors["Colors: Blue=Controllers, Green=Services, Orange=Repos, Purple=Datastores, Gray=FileStorage"]:::note
        DevProd["Dev vs Prod: H2=local-dev only; Postgres=production"]:::note
        CursorNote["Search: EmployeeService implements cursor-based pagination (stateless tokens)"]:::note
    end

    %% Click events for mapped components
    click README.md "https://github.com/sb10-part2-team2/sb10-hrbank-team2/blob/main/README.md"
    click Coderabbit "https://github.com/sb10-part2-team2/sb10-hrbank-team2/blob/main/.coderabbit.yaml"

    %% Styling
    classDef controller fill:#D0E8FF,stroke:#2B7CE9,color:#003366;
    classDef service fill:#E6F9E6,stroke:#2CA02C,color:#084C17;
    classDef repo fill:#FFE8CC,stroke:#D9822B,color:#6B3A00;
    classDef db fill:#EEDCFF,stroke:#7E57C2,color:#2E0854;
    classDef db_dev fill:#F5E6FF,stroke:#B77BD9,color:#4A1A6A;
    classDef filestorage fill:#EDEDED,stroke:#8C8C8C,color:#333333;
    classDef backup fill:#F7E9DC,stroke:#C16A00,color:#6B2F00;
    classDef app fill:#FFFFFF,stroke:#4A90E2,color:#0B3B5D;
    classDef infra fill:#F4F4F4,stroke:#9E9E9E,color:#333333;
    classDef infra_optional fill:#FAFAFA,stroke:#BDBDBD,color:#666666;
    classDef devtool fill:#F0F7FF,stroke:#4A90E2,color:#0B3B5D;
    classDef domain fill:#FFF7E6,stroke:#E6A800,color:#663E00;
    classDef dto fill:#FFF0F6,stroke:#D060A6,color:#5A1742;
    classDef integration fill:#F2FFF2,stroke:#66C66B,color:#0F6F2E;
    classDef scheduler fill:#FFF8E1,stroke:#F39C12,color:#6A3E00;
    classDef config fill:#F3F6FF,stroke:#7DA7FF,color:#113366;
    classDef note fill:#FFFFFF,stroke:#DDDDDD,color:#333333;
    classDef external fill:#F7FBFF,stroke:#BBD8FF,color:#0F4C81;
    classDef dbgroup fill:#F0E6FF,stroke:#A080FF,color:#3B2A66;
    classDef invis stroke:#ffffff,fill:#ffffff;

    %% Force vertical layout by connecting section tops to bottoms
    ContextDiagramTop --> ContextDiagramMid
    HRBankApp --> EmployeeController
    HRBankApp --> RailwayApp

    %% ensure scheduler node is visible and linked
    Scheduler -->|"internal to app"| RailwayApp
    Scheduler --> BackupService
    RailwayApp --> HRBankApp

    %% End of diagram
```
