# yasir2000/frappe-boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/yasir2000/frappe-boilerplate
- Repository: https://github.com/yasir2000/frappe-boilerplate

## Overview

Billing Application is a FastAPI service for user identity, invoice and invoice-item management, invoice workflow, file uploads, and WebSocket connections. A client reaches the API routes, which validate requests, enforce authentication where required, and use database models for persistent records; invoice operations also invoke workflow logging and transitions. The service entry point configures the API, database tables, static upload serving, and WebSocket endpoint. The upload routes write files directly; the separate file manager is documented but no sampled caller connects it. Arrows follow excerpts or README statements; unsampled subsystem wiring is omitted.

Main entry points: [`billing_app/api/routes.py`](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/api/routes.py) (API routes), [`main.py`](https://github.com/yasir2000/frappe-boilerplate/blob/main/main.py) (FastAPI service), [`billing_app/models/database.py`](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/models/database.py) (Invoices and items), [`billing_app/workflow/engine.py`](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/workflow/engine.py) (Invoice workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry_api["API entry"]
  node_service["FastAPI service<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
end

subgraph group_identity["Identity"]
  node_auth["Authentication<br/>[auth_handler.py]"]
end

subgraph group_billing["Billing domain"]
  node_billing_records["Invoices and items<br/>[database.py]"]
  node_workflow["Invoice workflow<br/>[engine.py]"]
  node_workflow_logs["Workflow history<br/>[database.py]"]
end

subgraph group_runtime["Runtime services"]
  node_file_manager["File manager<br/>[file_manager.py]"]
  node_file_records["File metadata<br/>[database.py]"]
  node_uploads["Upload files"]
  node_websocket_manager["WebSocket manager<br/>[ws_manager.py]"]
end

node_client(("API client"))
node_ws_client(("WebSocket client"))

node_client -->|"calls API"| node_routes
node_service -->|"mounts routes"| node_routes
node_service -->|"creates tables"| node_billing_records
node_routes -->|"validates requests"| node_schemas
node_routes -->|"authenticates users"| node_auth
node_auth -->|"reads users"| node_billing_records
node_routes -->|"reads and writes"| node_billing_records
node_routes -->|"logs invoice actions"| node_workflow
node_workflow -->|"reads and updates"| node_billing_records
node_workflow -->|"records history"| node_workflow_logs
node_routes -->|"writes uploads"| node_uploads
node_routes -->|"stores metadata"| node_file_records
node_service -->|"serves static files"| node_uploads
node_service -->|"handles connections"| node_websocket_manager
node_ws_client -->|"opens socket"| node_service
node_file_manager -->|"saves files"| node_uploads

click node_service "https://github.com/yasir2000/frappe-boilerplate/blob/main/main.py"
click node_routes "https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/api/routes.py"
click node_schemas "https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/models/schemas.py"
click node_auth "https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/auth/auth_handler.py"
click node_billing_records "https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/models/database.py"
click node_workflow "https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/workflow/engine.py"
click node_workflow_logs "https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/models/database.py"
click node_file_manager "https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/storage/file_manager.py"
click node_file_records "https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/models/database.py"
click node_websocket_manager "https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/websockets/ws_manager.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_service,node_routes,node_schemas,node_client,node_ws_client toneBlue
class node_auth toneAmber
class node_billing_records,node_workflow,node_workflow_logs toneMint
class node_file_manager,node_file_records,node_uploads,node_websocket_manager toneRose
```

## Components

### API entry

- [FastAPI service](https://github.com/yasir2000/frappe-boilerplate/blob/main/main.py): `main.py`
- [API routes](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/api/routes.py): `billing_app/api/routes.py`
- [Request schemas](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/models/schemas.py): `billing_app/models/schemas.py`

### Identity

- [Authentication](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/auth/auth_handler.py): `billing_app/auth/auth_handler.py`

### Billing domain

- [Invoices and items](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/models/database.py): `billing_app/models/database.py`
- [Invoice workflow](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/workflow/engine.py): `billing_app/workflow/engine.py`
- [Workflow history](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/models/database.py): `billing_app/models/database.py`

### Runtime services

- [File manager](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/storage/file_manager.py): `billing_app/storage/file_manager.py`
- [File metadata](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/models/database.py): `billing_app/models/database.py`
- **Upload files**
- [WebSocket manager](https://github.com/yasir2000/frappe-boilerplate/blob/main/billing_app/websockets/ws_manager.py): `billing_app/websockets/ws_manager.py`

### Other components

- **API client**
- **WebSocket client**

## Connections

- API client → API routes: calls API (evidence: `README.md`)
- FastAPI service → API routes: mounts routes (evidence: `main.py`)
- FastAPI service → Invoices and items: creates tables (evidence: `main.py`)
- API routes → Request schemas: validates requests (evidence: `billing_app/api/routes.py`)
- API routes → Authentication: authenticates users (evidence: `billing_app/api/routes.py`)
- Authentication → Invoices and items: reads users (evidence: `billing_app/auth/auth_handler.py`)
- API routes → Invoices and items: reads and writes (evidence: `billing_app/api/routes.py`)
- API routes → Invoice workflow: logs invoice actions (evidence: `billing_app/api/routes.py`)
- Invoice workflow → Invoices and items: reads and updates (evidence: `billing_app/workflow/engine.py`)
- Invoice workflow → Workflow history: records history (evidence: `billing_app/workflow/engine.py`)
- API routes → Upload files: writes uploads (evidence: `billing_app/api/routes.py`)
- API routes → File metadata: stores metadata (evidence: `billing_app/api/routes.py`)
- FastAPI service → Upload files: serves static files (evidence: `main.py`)
- FastAPI service → WebSocket manager: handles connections (evidence: `main.py`)
- WebSocket client → FastAPI service: opens socket (evidence: `README.md`)
- File manager → Upload files: saves files (evidence: `billing_app/storage/file_manager.py`)
