# lucaslims/l2sledger architecture

> Architecture diagram of the GitHub repository lucaslims/l2sledger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucaslims/l2sledger
- Repository: https://github.com/lucaslims/l2sledger

## Overview

L2SLedger is a financial cash-flow and audit system with a React SPA and a .NET Clean Architecture backend. The main user journey is to authenticate, manage transactions and financial periods, then inspect balances/reports or request exports; administrators also manage users and audit records. The graph preserves these domain branches and the export worker/storage layer. Source evidence is sampled for authentication, transactions, periods, and exports; other feature links are shown as unverified rather than inferred from naming alone.

Main entry points: [`backend/src/L2SLedger.Application/UseCases/Auth/AuthenticationService.cs`](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Application/UseCases/Auth/AuthenticationService.cs) (Authentication service), [`backend/src/L2SLedger.Infrastructure/BackgroundServices/ExportProcessorHostedService.cs`](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Infrastructure/BackgroundServices/ExportProcessorHostedService.cs) (Export processor), [`frontend/src/shared/lib/api/client.ts`](https://github.com/lucaslims/l2sledger/blob/main/frontend/src/shared/lib/api/client.ts) (HTTP API client), [`backend/src/L2SLedger.Infrastructure/Persistence/Repositories/TransactionRepository.cs`](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Infrastructure/Persistence/Repositories/TransactionRepository.cs) (Transaction persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["SPA routes and providers<br/>[App.tsx]"]
  node_authui["Authentication UI<br/>[authService.ts]"]
  node_api_client["HTTP API client<br/>[client.ts]"]
  node_transactions_ui["Transactions UI"]
  node_dashboard_ui["Dashboard UI"]
end

subgraph group_api["API boundary"]
  node_auth_api["Authentication endpoints<br/>[AuthController.cs]"]
  node_transaction_api["Transaction endpoints"]
  node_period_api["Period endpoints"]
end

subgraph group_finance["Financial workflows"]
  node_transactions["Transaction use cases<br/>[Transaction]"]
  node_periods["Financial periods<br/>[Periods]"]
  node_categories["Category management<br/>[Categories]"]
  node_balances["Balance calculation"]
  node_reports["Cash flow reporting<br/>[Reports]"]
  node_adjustments["Financial adjustments<br/>[Adjustments]"]
  node_exports["Export requests<br/>[Exports]"]
end

subgraph group_identity["Identity and administration"]
  node_auth_usecase["Authentication service"]
  node_firebase_auth["Firebase token validation"]
  node_user_domain["User identity and status<br/>[User.cs]"]
  node_admin_users["User administration<br/>[Users]"]
  node_audit["Immutable audit trail<br/>[Audit]"]
end

subgraph group_infra["Persistence and exports"]
  node_export_worker["Export processor"]
  node_export_storage[("Export file storage")]
  node_transaction_repo[("Transaction persistence")]
end

node_user(("Ledger user"))
node_firebase["Firebase Authentication"]
node_postgres[("PostgreSQL")]

node_user -->|"uses"| node_webapp
node_webapp -.->|"offers login"| node_authui
node_authui -->|"sends requests"| node_api_client
node_user -.->|"manages entries"| node_transactions_ui
node_transactions_ui -.->|"calls API"| node_transaction_api
node_dashboard_ui -.->|"requests summaries"| node_api_client
node_api_client -.->|"posts login"| node_auth_api
node_auth_api -->|"invokes login"| node_auth_usecase
node_auth_usecase -->|"validates token"| node_firebase_auth
node_firebase_auth -.->|"checks credentials"| node_firebase
node_auth_usecase -->|"checks status"| node_user_domain
node_transaction_api -->|"dispatches operations"| node_transactions
node_period_api -->|"dispatches operations"| node_periods
node_transactions -.->|"uses repository"| node_transaction_repo
node_transaction_repo -.->|"persists records"| node_postgres
node_balances -->|"reads transactions"| node_transaction_repo
node_balances -->|"reads categories"| node_categories
node_exports -.->|"queues work"| node_export_worker
node_export_worker -->|"cleans old files"| node_export_storage
node_export_worker -.->|"updates export records"| node_postgres
node_user -.->|"administers accounts"| node_admin_users
node_user -.->|"reviews events"| node_audit
node_user -.->|"views cash flow"| node_reports
node_user -.->|"records adjustments"| node_adjustments

click node_webapp "https://github.com/lucaslims/l2sledger/blob/main/frontend/src/app/App.tsx"
click node_authui "https://github.com/lucaslims/l2sledger/blob/main/frontend/src/features/auth/services/authService.ts"
click node_api_client "https://github.com/lucaslims/l2sledger/blob/main/frontend/src/shared/lib/api/client.ts"
click node_transactions_ui "https://github.com/lucaslims/l2sledger/tree/main/frontend/src/features/transactions"
click node_dashboard_ui "https://github.com/lucaslims/l2sledger/tree/main/frontend/src/features/dashboard"
click node_auth_api "https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.API/Controllers/AuthController.cs"
click node_transaction_api "https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.API/Controllers/TransactionsController.cs"
click node_period_api "https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.API/Controllers/PeriodsController.cs"
click node_auth_usecase "https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Application/UseCases/Auth/AuthenticationService.cs"
click node_firebase_auth "https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Infrastructure/Identity/FirebaseAuthService.cs"
click node_user_domain "https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Domain/Entities/User.cs"
click node_admin_users "https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Users"
click node_transactions "https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Transaction"
click node_periods "https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Periods"
click node_categories "https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Categories"
click node_balances "https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Application/Services/PeriodBalanceService.cs"
click node_reports "https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Reports"
click node_adjustments "https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Adjustments"
click node_audit "https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Audit"
click node_exports "https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Exports"
click node_export_worker "https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Infrastructure/BackgroundServices/ExportProcessorHostedService.cs"
click node_export_storage "https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Infrastructure/Services/FileStorageService.cs"
click node_transaction_repo "https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Infrastructure/Persistence/Repositories/TransactionRepository.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_authui,node_api_client,node_transactions_ui,node_dashboard_ui,node_user toneBlue
class node_auth_api,node_transaction_api,node_period_api,node_postgres toneAmber
class node_transactions,node_periods,node_categories,node_balances,node_reports,node_adjustments,node_exports toneMint
class node_auth_usecase,node_firebase_auth,node_user_domain,node_admin_users,node_audit toneRose
class node_export_worker,node_export_storage,node_transaction_repo,node_firebase toneIndigo
```

## Components

### Web application

- [SPA routes and providers](https://github.com/lucaslims/l2sledger/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Authentication UI](https://github.com/lucaslims/l2sledger/blob/main/frontend/src/features/auth/services/authService.ts): `frontend/src/features/auth/services/authService.ts`
- [HTTP API client](https://github.com/lucaslims/l2sledger/blob/main/frontend/src/shared/lib/api/client.ts): `frontend/src/shared/lib/api/client.ts`
- [Transactions UI](https://github.com/lucaslims/l2sledger/tree/main/frontend/src/features/transactions): `frontend/src/features/transactions`
- [Dashboard UI](https://github.com/lucaslims/l2sledger/tree/main/frontend/src/features/dashboard): `frontend/src/features/dashboard`

### API boundary

- [Authentication endpoints](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.API/Controllers/AuthController.cs): `backend/src/L2SLedger.API/Controllers/AuthController.cs`
- [Transaction endpoints](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.API/Controllers/TransactionsController.cs): `backend/src/L2SLedger.API/Controllers/TransactionsController.cs`
- [Period endpoints](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.API/Controllers/PeriodsController.cs): `backend/src/L2SLedger.API/Controllers/PeriodsController.cs`

### Financial workflows

- [Transaction use cases](https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Transaction): `backend/src/L2SLedger.Application/UseCases/Transaction`
- [Financial periods](https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Periods): `backend/src/L2SLedger.Application/UseCases/Periods`
- [Category management](https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Categories): `backend/src/L2SLedger.Application/UseCases/Categories`
- [Balance calculation](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Application/Services/PeriodBalanceService.cs): `backend/src/L2SLedger.Application/Services/PeriodBalanceService.cs`
- [Cash flow reporting](https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Reports): `backend/src/L2SLedger.Application/UseCases/Reports`
- [Financial adjustments](https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Adjustments): `backend/src/L2SLedger.Application/UseCases/Adjustments`
- [Export requests](https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Exports): `backend/src/L2SLedger.Application/UseCases/Exports`

### Identity and administration

- [Authentication service](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Application/UseCases/Auth/AuthenticationService.cs): `backend/src/L2SLedger.Application/UseCases/Auth/AuthenticationService.cs`
- [Firebase token validation](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Infrastructure/Identity/FirebaseAuthService.cs): `backend/src/L2SLedger.Infrastructure/Identity/FirebaseAuthService.cs`
- [User identity and status](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Domain/Entities/User.cs): `backend/src/L2SLedger.Domain/Entities/User.cs`
- [User administration](https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Users): `backend/src/L2SLedger.Application/UseCases/Users`
- [Immutable audit trail](https://github.com/lucaslims/l2sledger/tree/main/backend/src/L2SLedger.Application/UseCases/Audit): `backend/src/L2SLedger.Application/UseCases/Audit`

### Persistence and exports

- [Export processor](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Infrastructure/BackgroundServices/ExportProcessorHostedService.cs): `backend/src/L2SLedger.Infrastructure/BackgroundServices/ExportProcessorHostedService.cs`
- [Export file storage](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Infrastructure/Services/FileStorageService.cs): `backend/src/L2SLedger.Infrastructure/Services/FileStorageService.cs`
- [Transaction persistence](https://github.com/lucaslims/l2sledger/blob/main/backend/src/L2SLedger.Infrastructure/Persistence/Repositories/TransactionRepository.cs): `backend/src/L2SLedger.Infrastructure/Persistence/Repositories/TransactionRepository.cs`

### Other components

- **Ledger user**
- **Firebase Authentication**
- **PostgreSQL**

## Connections

- Ledger user → SPA routes and providers: uses (evidence: `frontend/src/app/App.tsx`)
- SPA routes and providers → Authentication UI: offers login
- Authentication UI → HTTP API client: sends requests (evidence: `frontend/src/features/auth/services/authService.ts`)
- Ledger user → Transactions UI: manages entries
- Transactions UI → Transaction endpoints: calls API
- Dashboard UI → HTTP API client: requests summaries
- HTTP API client → Authentication endpoints: posts login
- Authentication endpoints → Authentication service: invokes login (evidence: `backend/src/L2SLedger.API/Controllers/AuthController.cs`)
- Authentication service → Firebase token validation: validates token (evidence: `backend/src/L2SLedger.Application/UseCases/Auth/AuthenticationService.cs`)
- Firebase token validation → Firebase Authentication: checks credentials
- Authentication service → User identity and status: checks status (evidence: `backend/src/L2SLedger.Application/UseCases/Auth/AuthenticationService.cs`)
- Transaction endpoints → Transaction use cases: dispatches operations (evidence: `backend/src/L2SLedger.API/Controllers/TransactionsController.cs`)
- Period endpoints → Financial periods: dispatches operations (evidence: `backend/src/L2SLedger.API/Controllers/PeriodsController.cs`)
- Transaction use cases → Transaction persistence: uses repository
- Transaction persistence → PostgreSQL: persists records
- Balance calculation → Transaction persistence: reads transactions (evidence: `backend/src/L2SLedger.Application/Services/PeriodBalanceService.cs`)
- Balance calculation → Category management: reads categories (evidence: `backend/src/L2SLedger.Application/Services/PeriodBalanceService.cs`)
- Export requests → Export processor: queues work
- Export processor → Export file storage: cleans old files (evidence: `backend/src/L2SLedger.Infrastructure/BackgroundServices/ExportProcessorHostedService.cs`)
- Export processor → PostgreSQL: updates export records
- Ledger user → User administration: administers accounts
- Ledger user → Immutable audit trail: reviews events
- Ledger user → Cash flow reporting: views cash flow
- Ledger user → Financial adjustments: records adjustments
