# oprekable/bank-reconcile architecture

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

- Interactive diagram: https://gitdiagram.com/oprekable/bank-reconcile
- Repository: https://github.com/oprekable/bank-reconcile

## Overview

##### Project Type and Purpose
- This is a standalone Go-based CLI application (using Cobra) that performs:
- “sample” command – generates system and bank CSVs
- “process” command – reads CSVs, reconciles transactions, writes reports
- It employs a layered/hexagonal architecture with DI (Google Wire), unit tests (mockery), and SQLite as an embedded database.

##### Main Components
A. CLI Layer (Green)
1. Cobra Root & Commands
– cmd/root/root.go
– cmd/sample, cmd/process, cmd/version
2. CLI Handlers
– internal/app/handler/hcli/*
B. Service Layer (Blue)
– internal/app/service/{sample,process}
– business rules for sample generation & reconciliation
C. Repository Layer (Orange)
– internal/app/repository/{sample,process}
– imports data into SQLite, executes queries
D. Database (Gray)
– SQLite (via internal/pkg/driver/sql/sqlite.go)
– schemas & persistence
E. Parser Modules (Purple)
– internal/pkg/reconcile/parser
- banks/* (bca, bni, default)
- systems/default_system
F. Configuration & Utilities (Yellow)
– internal/app/config (app.toml, sqlite.toml, reconciliation.toml)
– internal/pkg/utils (file I/O, logging, shutdown)
G. Dependency Injection (Wire)
– internal/inject/wire_gen.go

##### Relationships & Data Flows
- User → CLI Layer:
- Enters “bank-reconcile sample” or “process”
- CLI Layer → Handler:
- Parses flags, constructs input DTOs
- Handler → Service:
- Calls SampleService.Generate, ProcessService.GenerateReconciliation
- Service ↔ Repository:
- SampleService writes generated data to CSV (FileSystem)
- ProcessService:
– Reads CSV via Parser Modules → transforms into domain entities
– Calls Repository to import into DB
– Calls Repository to run reconciliation queries
– Retrieves summary & unmatched sets
- Repository ↔ Database:
- Executes SQL via sqlite driver
- Service → Reports:
- Exports matched/unmatched CSV reports via FileSystem
- Throughout all layers, components for logging, error handling, profiling, and shutdown are invoked.

##### Architectural Patterns & Principles
- Clean/Hexagonal Architecture: clear separation between CLI, Use Cases (Service), Persistence (Repository), and External Systems (FS, DB)
- Dependency Injection via Wire: decouples construction of handlers, services, repositories
- Repository Pattern: abstracts database operations
- Single-Responsibility: each package/folder has distinct concern (handler, service, repository, parser, config)
- Mockability: interfaces in each layer (under _mock) enable high test coverage

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User/Terminal"]:::external

    subgraph "CLI Layer"
        subgraph "Cobra Commands"
            RootCmd["root.go"]:::cli
            SampleCmd["sample.go"]:::cli
            ProcessCmd["process.go"]:::cli
            VersionCmd["version.go"]:::cli
        end
        subgraph "Command Helpers & Tests"
            Helper["cmd/helper"]:::cli
        end
        subgraph "CLI Handlers"
            Handlers["internal/app/handler/hcli"]:::cli
        end
    end

    subgraph "Service Layer"
        SampleService["SampleService"]:::service
        ProcessService["ProcessService"]:::service
    end

    subgraph "Parser Modules"
        BankParsers["Bank Parsers"]:::parser
        SystemParsers["System Parsers"]:::parser
    end

    subgraph "Repository Layer"
        SampleRepo["Sample Repository"]:::repo
        ProcessRepo["Process Repository"]:::repo
    end

    Database["SQLite DB"]:::db
    FS["File System"]:::external

    subgraph "Configuration & Utilities"
        Config["Config"]:::config
        Utils["Utilities"]:::config
    end

    subgraph "Dependency Injection (Wire)"
        Wire["Wire Setup & Components"]:::di
        Components["DI Components"]:::di
    end

    %% Data Flows
    User --> RootCmd
    User --> SampleCmd
    User --> ProcessCmd
    User --> VersionCmd
    RootCmd --> Handlers
    SampleCmd --> Handlers
    ProcessCmd --> Handlers
    Handlers -->|Invoke sample| SampleService
    Handlers -->|Invoke process| ProcessService

    SampleService -->|Generate sample| SampleRepo
    SampleRepo -->|Write to DB| Database
    SampleService -->|Write CSVs| FS

    ProcessService -->|Parse CSV| BankParsers
    ProcessService -->|Parse CSV| SystemParsers
    BankParsers -->|Parsed Data| ProcessService
    SystemParsers -->|Parsed Data| ProcessService
    ProcessService -->|Import & Reconcile| ProcessRepo
    ProcessRepo -->|DB Queries| Database
    ProcessService -->|Write reports| FS

    %% Config & Utils flows
    Config --> Handlers
    Config --> SampleService
    Config --> ProcessService
    Config --> SampleRepo
    Config --> ProcessRepo
    Utils --> SampleService
    Utils --> ProcessService
    Utils --> Handlers

    %% DI flows
    Wire --> Handlers
    Wire --> SampleService
    Wire --> ProcessService
    Wire --> SampleRepo
    Wire --> ProcessRepo
    Components --> SampleService
    Components --> ProcessService
    Components --> SampleRepo
    Components --> ProcessRepo

    %% Click Events
    click RootCmd "https://github.com/oprekable/bank-reconcile/blob/main/cmd/root/root.go"
    click SampleCmd "https://github.com/oprekable/bank-reconcile/blob/main/cmd/sample/sample.go"
    click ProcessCmd "https://github.com/oprekable/bank-reconcile/blob/main/cmd/process/process.go"
    click VersionCmd "https://github.com/oprekable/bank-reconcile/blob/main/cmd/version/version.go"
    click Helper "https://github.com/oprekable/bank-reconcile/blob/main/cmd/helper/helper.go"
    click Handlers "https://github.com/oprekable/bank-reconcile/blob/main/internal/app/handler/hcli/register.go"
    click SampleService "https://github.com/oprekable/bank-reconcile/blob/main/internal/app/service/sample/svc.go"
    click ProcessService "https://github.com/oprekable/bank-reconcile/blob/main/internal/app/service/process/svc.go"
    click SampleRepo "https://github.com/oprekable/bank-reconcile/blob/main/internal/app/repository/sample/db.go"
    click ProcessRepo "https://github.com/oprekable/bank-reconcile/blob/main/internal/app/repository/process/db.go"
    click Database "https://github.com/oprekable/bank-reconcile/blob/main/internal/pkg/driver/sql/sqlite.go"
    click Config "https://github.com/oprekable/bank-reconcile/blob/main/internal/app/config/config.go"
    click Utils "https://github.com/oprekable/bank-reconcile/blob/main/internal/pkg/utils/csvhelper/csvhelper.go"
    click BankParsers "https://github.com/oprekable/bank-reconcile/blob/main/internal/pkg/reconcile/parser/banks/bca/bank_parser_bca.go"
    click SystemParsers "https://github.com/oprekable/bank-reconcile/blob/main/internal/pkg/reconcile/parser/systems/default_system/system_parser_default.go"
    click Wire "https://github.com/oprekable/bank-reconcile/blob/main/internal/inject/wire_gen.go"
    click Components "https://github.com/oprekable/bank-reconcile/blob/main/internal/app/component/csqlite/csqlite.go"

    %% Styles
    classDef cli fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef service fill:#a2d0f5,stroke:#333,stroke-width:1px
    classDef repo fill:#f5cfa2,stroke:#333,stroke-width:1px
    classDef db fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef parser fill:#d5a2f5,stroke:#333,stroke-width:1px
    classDef config fill:#f5f1a2,stroke:#333,stroke-width:1px
    classDef di fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef external fill:#ffffff,stroke:#333,stroke-width:1px
```
