# janupoju-sudo/lpl-financial-hackathon architecture

> Architecture diagram of the GitHub repository janupoju-sudo/lpl-financial-hackathon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/janupoju-sudo/lpl-financial-hackathon
- Repository: https://github.com/janupoju-sudo/lpl-financial-hackathon

## Overview

Ledgerline is an AI-assisted back office for independent advisor practices. The main workflow runs from document and bill handling through approval and ledger posting, then surfaces financial statements, revenue reconciliation, Q&A, and export in the workspace. The README also describes onboarding, library search, vendor memory, CSV import, and Google Drive import. Backend excerpts show selected handlers and shared services; several documented capabilities have unsampled implementations, so their links are marked unverified rather than inferred as calls.

Main entry points: [`frontend/lib/api.ts`](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/lib/api.ts) (Typed API client), [`backend/src/shared/repo.py`](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/repo.py) (Entity repository), [`frontend/components/workspace.tsx`](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/components/workspace.tsx) (Workspace), [`backend/src/handlers/bills.py`](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/handlers/bills.py) (Bill decisions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Practice workspace"]
  node_workspace["Workspace<br/>[workspace.tsx]"]
  node_onboarding["Onboarding<br/>[wizard.tsx]"]
  node_landing["Landing experience<br/>[landing.tsx]"]
  node_api_client["Typed API client<br/>[api.ts]"]
  node_drive_import["Drive import"]
end

subgraph group_operations["Documents and bills"]
  node_document_ingest["Document ingestion"]
  node_document_handlers["Document handlers<br/>[documents.py]"]
  node_bill_handlers["Bill decisions<br/>[bills.py]"]
  node_approval_rules["Approval rules<br/>[rules_engine.py]"]
  node_bill_workflow["Bill workflow"]
  node_transactions["Transactions<br/>[transactions.py]"]
end

subgraph group_insights["Financial insights"]
  node_financials["Financial statements<br/>[api.py]"]
  node_reconciliation["Revenue reconciliation<br/>[reconciliation.py]"]
  node_ask["Ask books<br/>[handler.py]"]
  node_ask_context["Answer context<br/>[context.py]"]
  node_bedrock["Bedrock model<br/>[bedrock.py]"]
  node_export["ZIP export<br/>[handler.py]"]
end

subgraph group_platform["Backend services"]
  node_repository["Entity repository<br/>[repo.py]"]
  node_ledger["Ledger services<br/>[ledger.py]"]
  node_ddb[("DynamoDB access<br/>[ddb.py]")]
  node_auth["Caller identity<br/>[auth.py]"]
  node_http["HTTP routing<br/>[http.py]"]
end

node_advisor(("Practice team"))

node_advisor -->|"uses"| node_workspace
node_workspace -->|"opens"| node_onboarding
node_workspace -->|"opens"| node_landing
node_workspace -.->|"requests"| node_api_client
node_workspace -.->|"offers"| node_drive_import
node_api_client -.->|"calls API"| node_document_handlers
node_api_client -.->|"calls API"| node_bill_handlers
node_api_client -.->|"calls API"| node_financials
node_api_client -.->|"calls API"| node_reconciliation
node_api_client -.->|"calls API"| node_ask
node_api_client -.->|"calls API"| node_export
node_document_ingest -.->|"stores records"| node_repository
node_document_handlers -.->|"reads and writes"| node_repository
node_bill_handlers -->|"reads and writes"| node_repository
node_bill_handlers -.->|"evaluates rules"| node_approval_rules
node_bill_handlers -->|"dispatches workflow"| node_bill_workflow
node_bill_handlers -.->|"posts entries"| node_ledger
node_transactions -.->|"updates ledger"| node_ledger
node_financials -.->|"uses"| node_reconciliation
node_financials -.->|"summarizes books"| node_ask_context
node_ask -.->|"builds context"| node_ask_context
node_ask -->|"invokes model"| node_bedrock
node_ask -->|"loads documents"| node_repository
node_export -->|"builds financials"| node_financials
node_export -->|"lists documents"| node_repository
node_financials -->|"reads ledger"| node_ddb
node_reconciliation -->|"reads revenue"| node_ddb
node_repository -.->|"queries entities"| node_ddb
node_http -.->|"routes requests"| node_auth

click node_workspace "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/components/workspace.tsx"
click node_onboarding "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/components/onboarding/wizard.tsx"
click node_landing "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/components/landing.tsx"
click node_api_client "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/lib/api.ts"
click node_drive_import "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/components/google-drive-import.tsx"
click node_document_ingest "https://github.com/janupoju-sudo/lpl-financial-hackathon/tree/main/backend/src/ingest"
click node_document_handlers "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/handlers/documents.py"
click node_bill_handlers "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/handlers/bills.py"
click node_approval_rules "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/rules_engine.py"
click node_bill_workflow "https://github.com/janupoju-sudo/lpl-financial-hackathon/tree/main/backend/src/workflow"
click node_transactions "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/handlers/transactions.py"
click node_financials "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/financials/api.py"
click node_reconciliation "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/financials/reconciliation.py"
click node_ask "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/ask/handler.py"
click node_ask_context "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/ask/context.py"
click node_bedrock "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/ask/bedrock.py"
click node_export "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/export/handler.py"
click node_repository "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/repo.py"
click node_ledger "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/ledger.py"
click node_ddb "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/ddb.py"
click node_auth "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/auth.py"
click node_http "https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/http.py"

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_workspace,node_onboarding,node_landing,node_api_client,node_drive_import toneBlue
class node_document_ingest,node_document_handlers,node_bill_handlers,node_approval_rules,node_bill_workflow,node_transactions toneAmber
class node_financials,node_reconciliation,node_ask,node_ask_context,node_bedrock,node_export toneMint
class node_repository,node_ledger,node_ddb,node_auth,node_http toneRose
class node_advisor toneIndigo
```

## Components

### Practice workspace

- [Workspace](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/components/workspace.tsx): `frontend/components/workspace.tsx`
- [Onboarding](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/components/onboarding/wizard.tsx): `frontend/components/onboarding/wizard.tsx`
- [Landing experience](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/components/landing.tsx): `frontend/components/landing.tsx`
- [Typed API client](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Drive import](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/frontend/components/google-drive-import.tsx): `frontend/components/google-drive-import.tsx`

### Documents and bills

- [Document ingestion](https://github.com/janupoju-sudo/lpl-financial-hackathon/tree/main/backend/src/ingest): `backend/src/ingest`
- [Document handlers](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/handlers/documents.py): `backend/src/handlers/documents.py`
- [Bill decisions](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/handlers/bills.py): `backend/src/handlers/bills.py`
- [Approval rules](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/rules_engine.py): `backend/src/shared/rules_engine.py`
- [Bill workflow](https://github.com/janupoju-sudo/lpl-financial-hackathon/tree/main/backend/src/workflow): `backend/src/workflow`
- [Transactions](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/handlers/transactions.py): `backend/src/handlers/transactions.py`

### Financial insights

- [Financial statements](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/financials/api.py): `backend/src/financials/api.py`
- [Revenue reconciliation](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/financials/reconciliation.py): `backend/src/financials/reconciliation.py`
- [Ask books](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/ask/handler.py): `backend/src/ask/handler.py`
- [Answer context](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/ask/context.py): `backend/src/ask/context.py`
- [Bedrock model](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/ask/bedrock.py): `backend/src/ask/bedrock.py`
- [ZIP export](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/export/handler.py): `backend/src/export/handler.py`

### Backend services

- [Entity repository](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/repo.py): `backend/src/shared/repo.py`
- [Ledger services](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/ledger.py): `backend/src/shared/ledger.py`
- [DynamoDB access](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/ddb.py): `backend/src/shared/ddb.py`
- [Caller identity](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/auth.py): `backend/src/shared/auth.py`
- [HTTP routing](https://github.com/janupoju-sudo/lpl-financial-hackathon/blob/main/backend/src/shared/http.py): `backend/src/shared/http.py`

### Other components

- **Practice team**

## Connections

- Practice team → Workspace: uses (evidence: `README.md`)
- Workspace → Onboarding: opens (evidence: `frontend/components/workspace.tsx`)
- Workspace → Landing experience: opens (evidence: `frontend/components/workspace.tsx`)
- Workspace → Typed API client: requests
- Workspace → Drive import: offers (evidence: `frontend/components/workspace.tsx`)
- Typed API client → Document handlers: calls API (evidence: `README.md`)
- Typed API client → Bill decisions: calls API (evidence: `README.md`)
- Typed API client → Financial statements: calls API (evidence: `README.md`)
- Typed API client → Revenue reconciliation: calls API (evidence: `README.md`)
- Typed API client → Ask books: calls API (evidence: `README.md`)
- Typed API client → ZIP export: calls API (evidence: `README.md`)
- Document ingestion → Entity repository: stores records
- Document handlers → Entity repository: reads and writes
- Bill decisions → Entity repository: reads and writes (evidence: `backend/src/handlers/bills.py`)
- Bill decisions → Approval rules: evaluates rules
- Bill decisions → Bill workflow: dispatches workflow (evidence: `backend/src/handlers/bills.py`)
- Bill decisions → Ledger services: posts entries (evidence: `backend/src/handlers/bills.py`)
- Transactions → Ledger services: updates ledger
- Financial statements → Revenue reconciliation: uses
- Financial statements → Answer context: summarizes books
- Ask books → Answer context: builds context
- Ask books → Bedrock model: invokes model (evidence: `backend/src/ask/handler.py`)
- Ask books → Entity repository: loads documents (evidence: `backend/src/ask/handler.py`)
- ZIP export → Financial statements: builds financials (evidence: `backend/src/export/handler.py`)
- ZIP export → Entity repository: lists documents (evidence: `backend/src/export/handler.py`)
- Financial statements → DynamoDB access: reads ledger (evidence: `backend/src/financials/handler.py`)
- Revenue reconciliation → DynamoDB access: reads revenue (evidence: `backend/src/financials/handler.py`)
- Entity repository → DynamoDB access: queries entities (evidence: `backend/src/shared/repo.py`)
- HTTP routing → Caller identity: routes requests (evidence: `backend/src/shared/auth.py`)
