# sourasishbasu/ledgerly architecture

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

- Interactive diagram: https://gitdiagram.com/sourasishbasu/ledgerly
- Repository: https://github.com/sourasishbasu/ledgerly

## Overview

##### Main Components
- Frontend: Although the file tree does not include a dedicated “frontend” folder, the README reveals that the user interface is built with NextJS. Represent this as a standalone “Website/NextJS” component that interacts with the backend API.
- Backend API Service: Use the “services/backend” directory as the basis for the core FastAPI service. This service handles user actions (registration, login, CRUD operations for receipts) and interacts with the database.
- Receipt OCR Service: Derived from “services/receipt-ocr,” this helper service processes receipt images using language models and extracts data. This is deployed as a container and mapped to an AWS Lambda function.
- Database: Represent the Postgres database (using AWS RDS or a containerized “postgres” option mentioned in the README, with the schema provided in ledgerly.sql). Label it appropriately with details like DB credentials and connection endpoints.
- AWS Storage: Include an “S3 Bucket” component for image storage. It serves as the repository for receipt images used by the backend.
- AWS Compute: Represent AWS Lambda (for running the receipt-ocr container image) and EC2 (for hosting Docker containers and running the main services).
- Reverse Proxy: Add Traefik as a dynamic reverse proxy that handles the routing of web requests, SSL termination (via Let's Encrypt), and log management.
- Monitoring Stack: Indicate the monitoring infrastructure including Prometheus (with its scraping configs), Grafana (for dashboard visualization), Node Exporter, cAdvisor, and GoAccess. These elements are crucial for performance and availability tracking.

##### Relationships and Interactions
- The frontend (NextJS website) for user interfaces.
- The backend API (FastAPI) service for RESTful requests.
- Within the backend service, denote interactions with:
- The S3 Bucket for image upload and retrieval.
- Container orchestration via Docker Compose, linking all containerized components (backend, receipt OCR, Traefik, monitoring tools) to the underlying EC2 host.
- For monitoring, show Prometheus scraping endpoints on all containerized services (via Node Exporter, cAdvisor) and Grafana reading from Prometheus. Also include GoAccess streaming logs from Traefik.

##### Architectural Patterns & Key Technologies
- Microservices: The separation between the backend (API) and receipt OCR logic demonstrates a microservices-type approach.
- Containerization: Emphasize the consistent use of Docker for reproducible deployments.
- Infrastructure-as-Code: Note the use of Ansible playbooks and Docker Compose for automated deployments.
- Cloud Integration: AWS services (ECR, Lambda, RDS, S3, EC2) and external integrations (Traefik, monitoring tools) are integral to the system.
- Observability: The inclusion of Prometheus, Grafana, Node Exporter, cAdvisor, and GoAccess indicates a strong focus on monitoring and log aggregation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Users
    User["External Users"]:::external

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        T["Traefik Reverse Proxy"]:::micro
        DC["Docker Compose"]:::deployment
        AD["Ansible Deployment"]:::deployment
        EC2["AWS EC2 Host"]:::aws
        ECR["AWS ECR"]:::aws
        Lambda["AWS Lambda"]:::aws
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Website/NextJS"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        API["FastAPI Backend"]:::micro
        OCR["Receipt OCR Service"]:::micro
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["Postgres Database"]:::db
        S3["AWS S3 Bucket"]:::aws
    end

    %% Monitoring Layer
    subgraph "Monitoring Layer"
        Prom["Prometheus"]:::monitor
        Graf["Grafana"]:::monitor
        NodeExp["Node Exporter"]:::monitor
        cAd["cAdvisor"]:::monitor
        GoA["GoAccess"]:::monitor
    end

    %% Connections
    User -->|"HTTP_Request"| T
    T -->|"UI_Route"| FE
    T -->|"API_Route"| API
    T -->|"Log_Stream"| GoA

    API -->|"CRUD"| DB
    API -->|"Image_Upload"| S3
    API -->|"Trigger_OCR"| OCR
    OCR -->|"Container_to_Lambda"| Lambda

    %% Container orchestration links
    DC --> T
    DC --> API
    DC --> OCR
    DC --> NodeExp
    DC --> cAd
    DC --> EC2
    AD --> DC
    ECR --> DC

    %% Monitoring flows
    NodeExp -->|"Metrics_Scrape"| Prom
    cAd -->|"Metrics_Scrape"| Prom
    Prom -->|"Data_Feed"| Graf

    %% Class Definitions
    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef frontend fill:#AEDFF7,stroke:#000000,stroke-width:1px;
    classDef micro fill:#C0E0FF,stroke:#000000,stroke-width:1px;
    classDef db fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef aws fill:#FDEBD0,stroke:#E67E22,stroke-width:2px;
    classDef infra fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef monitor fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef deployment fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;

    %% Click Events
    click API "https://github.com/sourasishbasu/ledgerly/blob/main/services/backend/app/app.py"
    click OCR "https://github.com/sourasishbasu/ledgerly/blob/main/services/receipt-ocr/app.py"
    click DB "https://github.com/sourasishbasu/ledgerly/blob/main/services/ledgerly.sql"
    click AD "https://github.com/sourasishbasu/ledgerly/blob/main/deployment/ansible/playbook.yml"
    click DC "https://github.com/sourasishbasu/ledgerly/blob/main/deployment/docker-compose.yml"
    click Graf "https://github.com/sourasishbasu/ledgerly/blob/main/deployment/grafana/datasources.yml"
    click Prom "https://github.com/sourasishbasu/ledgerly/blob/main/deployment/prometheus/prometheus.yml"
```
