# fannyzf/notesbang architecture

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

- Interactive diagram: https://gitdiagram.com/fannyzf/notesbang
- Repository: https://github.com/fannyzf/notesbang

## Overview

NotesBang is a bilingual content-scoring and rewriting product. Users submit pasted or uploaded copy, receive an asynchronous platform-aware committee scorecard, then request a full rewrite or title/hook variants, export results, or share a scorecard. The map also includes authentication, billing, administration, and privacy-friendly traffic tracking. The README documents product capabilities beyond the sampled excerpts; links to those capabilities are included only where the tree provides a supporting module path.

Main entry points: [`backend/app/main.py`](https://github.com/fannyzf/notesbang/blob/master/backend/app/main.py) (FastAPI app), [`backend/app/api/routes_documents.py`](https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_documents.py) (Document routes), [`backend/app/db/base.py`](https://github.com/fannyzf/notesbang/blob/master/backend/app/db/base.py) (Application data), [`backend/app/workers/jobs.py`](https://github.com/fannyzf/notesbang/blob/master/backend/app/workers/jobs.py) (Analysis task)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_studio["Studio UI<br/>[page.tsx]"]
  node_admin_ui["Admin console<br/>[page.tsx]"]
  node_sharing["Share routes<br/>[routes_share.py]"]
end

subgraph group_content["Content workflow"]
  node_documents["Document routes"]
  node_parser["Upload parser<br/>[text_parser.py]"]
  node_jobs_api["Job routes<br/>[routes_jobs.py]"]
  node_worker["Job runner<br/>[runner.py]"]
  node_analysis_jobs["Analysis task<br/>[jobs.py]"]
  node_scoring["Committee scoring<br/>[scoring.py]"]
  node_rubric["Rubrics<br/>[rubric.py]"]
  node_llm["LLM gateway<br/>[gateway.py]"]
  node_rewriting["Rewrite engine<br/>[rewrite.py]"]
  node_export["Export writers"]
end

subgraph group_platform["Platform services"]
  node_api["FastAPI app<br/>[main.py]"]
  node_auth["Auth routes<br/>[routes_auth.py]"]
  node_billing["Billing routes<br/>[routes_billing.py]"]
  node_billing_service["Billing service<br/>[billing.py]"]
  node_payment_gateway["Payment gateway<br/>[gateway.py]"]
  node_storage["Object storage<br/>[storage.py]"]
  node_database[("Application data<br/>[base.py]")]
end

subgraph group_operations["Operations"]
  node_admin["Admin routes<br/>[routes_admin.py]"]
  node_tracking["Traffic tracking<br/>[routes_track.py]"]
end

node_user(("User"))
node_provider["Payment provider"]

node_user -->|"uses"| node_studio
node_studio -->|"calls API"| node_api
node_api -->|"dispatches"| node_auth
node_api -->|"dispatches"| node_documents
node_api -->|"dispatches"| node_jobs_api
node_api -->|"dispatches"| node_billing
node_api -->|"dispatches"| node_sharing
node_api -->|"dispatches"| node_admin
node_api -->|"dispatches"| node_tracking
node_documents -->|"parses uploads"| node_parser
node_documents -->|"stores documents"| node_database
node_documents -->|"enqueues analysis"| node_worker
node_jobs_api -->|"reads job status"| node_database
node_worker -->|"executes task"| node_analysis_jobs
node_analysis_jobs -->|"runs scoring"| node_scoring
node_scoring -->|"uses criteria"| node_rubric
node_scoring -->|"requests judgments"| node_llm
node_analysis_jobs -->|"saves results"| node_database
node_documents -->|"requests rewrite"| node_rewriting
node_rewriting -->|"generates variants"| node_llm
node_documents -->|"builds export"| node_export
node_documents -->|"uses artifacts"| node_storage
node_sharing -->|"reads and writes shares"| node_database
node_billing -->|"settles charges"| node_billing_service
node_billing -->|"creates checkout"| node_payment_gateway
node_payment_gateway -.->|"uses provider"| node_provider
node_billing_service -->|"updates wallet"| node_database
node_admin_ui -->|"calls API"| node_api
node_admin -->|"reads and updates"| node_database
node_tracking -->|"records views"| node_database

click node_studio "https://github.com/fannyzf/notesbang/blob/master/frontend/app/studio/page.tsx"
click node_admin_ui "https://github.com/fannyzf/notesbang/blob/master/frontend/app/admin/page.tsx"
click node_api "https://github.com/fannyzf/notesbang/blob/master/backend/app/main.py"
click node_auth "https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_auth.py"
click node_documents "https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_documents.py"
click node_parser "https://github.com/fannyzf/notesbang/blob/master/backend/app/parsers/text_parser.py"
click node_jobs_api "https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_jobs.py"
click node_worker "https://github.com/fannyzf/notesbang/blob/master/backend/app/workers/runner.py"
click node_analysis_jobs "https://github.com/fannyzf/notesbang/blob/master/backend/app/workers/jobs.py"
click node_scoring "https://github.com/fannyzf/notesbang/blob/master/backend/app/content/scoring.py"
click node_rubric "https://github.com/fannyzf/notesbang/blob/master/backend/app/content/rubric.py"
click node_llm "https://github.com/fannyzf/notesbang/blob/master/backend/app/llm/gateway.py"
click node_rewriting "https://github.com/fannyzf/notesbang/blob/master/backend/app/content/rewrite.py"
click node_export "https://github.com/fannyzf/notesbang/tree/master/backend/app/exporters"
click node_sharing "https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_share.py"
click node_billing "https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_billing.py"
click node_billing_service "https://github.com/fannyzf/notesbang/blob/master/backend/app/services/billing.py"
click node_payment_gateway "https://github.com/fannyzf/notesbang/blob/master/backend/app/billing/gateway.py"
click node_admin "https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_admin.py"
click node_tracking "https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_track.py"
click node_storage "https://github.com/fannyzf/notesbang/blob/master/backend/app/services/storage.py"
click node_database "https://github.com/fannyzf/notesbang/blob/master/backend/app/db/base.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_studio,node_admin_ui,node_sharing,node_user toneBlue
class node_documents,node_parser,node_jobs_api,node_worker,node_analysis_jobs,node_scoring,node_rubric,node_llm,node_rewriting,node_export toneAmber
class node_api,node_auth,node_billing,node_billing_service,node_payment_gateway,node_storage,node_database toneMint
class node_admin,node_tracking toneRose
class node_provider toneIndigo
```

## Components

### User experience

- [Studio UI](https://github.com/fannyzf/notesbang/blob/master/frontend/app/studio/page.tsx): `frontend/app/studio/page.tsx`
- [Admin console](https://github.com/fannyzf/notesbang/blob/master/frontend/app/admin/page.tsx): `frontend/app/admin/page.tsx`
- [Share routes](https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_share.py): `backend/app/api/routes_share.py`

### Content workflow

- [Document routes](https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_documents.py): `backend/app/api/routes_documents.py`
- [Upload parser](https://github.com/fannyzf/notesbang/blob/master/backend/app/parsers/text_parser.py): `backend/app/parsers/text_parser.py`
- [Job routes](https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_jobs.py): `backend/app/api/routes_jobs.py`
- [Job runner](https://github.com/fannyzf/notesbang/blob/master/backend/app/workers/runner.py): `backend/app/workers/runner.py`
- [Analysis task](https://github.com/fannyzf/notesbang/blob/master/backend/app/workers/jobs.py): `backend/app/workers/jobs.py`
- [Committee scoring](https://github.com/fannyzf/notesbang/blob/master/backend/app/content/scoring.py): `backend/app/content/scoring.py`
- [Rubrics](https://github.com/fannyzf/notesbang/blob/master/backend/app/content/rubric.py): `backend/app/content/rubric.py`
- [LLM gateway](https://github.com/fannyzf/notesbang/blob/master/backend/app/llm/gateway.py): `backend/app/llm/gateway.py`
- [Rewrite engine](https://github.com/fannyzf/notesbang/blob/master/backend/app/content/rewrite.py): `backend/app/content/rewrite.py`
- [Export writers](https://github.com/fannyzf/notesbang/tree/master/backend/app/exporters): `backend/app/exporters`

### Platform services

- [FastAPI app](https://github.com/fannyzf/notesbang/blob/master/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_auth.py): `backend/app/api/routes_auth.py`
- [Billing routes](https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_billing.py): `backend/app/api/routes_billing.py`
- [Billing service](https://github.com/fannyzf/notesbang/blob/master/backend/app/services/billing.py): `backend/app/services/billing.py`
- [Payment gateway](https://github.com/fannyzf/notesbang/blob/master/backend/app/billing/gateway.py): `backend/app/billing/gateway.py`
- [Object storage](https://github.com/fannyzf/notesbang/blob/master/backend/app/services/storage.py): `backend/app/services/storage.py`
- [Application data](https://github.com/fannyzf/notesbang/blob/master/backend/app/db/base.py): `backend/app/db/base.py`

### Operations

- [Admin routes](https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_admin.py): `backend/app/api/routes_admin.py`
- [Traffic tracking](https://github.com/fannyzf/notesbang/blob/master/backend/app/api/routes_track.py): `backend/app/api/routes_track.py`

### Other components

- **User**
- **Payment provider**

## Connections

- User → Studio UI: uses
- Studio UI → FastAPI app: calls API
- FastAPI app → Auth routes: dispatches
- FastAPI app → Document routes: dispatches
- FastAPI app → Job routes: dispatches
- FastAPI app → Billing routes: dispatches
- FastAPI app → Share routes: dispatches
- FastAPI app → Admin routes: dispatches
- FastAPI app → Traffic tracking: dispatches
- Document routes → Upload parser: parses uploads
- Document routes → Application data: stores documents
- Document routes → Job runner: enqueues analysis
- Job routes → Application data: reads job status
- Job runner → Analysis task: executes task
- Analysis task → Committee scoring: runs scoring
- Committee scoring → Rubrics: uses criteria
- Committee scoring → LLM gateway: requests judgments
- Analysis task → Application data: saves results
- Document routes → Rewrite engine: requests rewrite
- Rewrite engine → LLM gateway: generates variants
- Document routes → Export writers: builds export
- Document routes → Object storage: uses artifacts
- Share routes → Application data: reads and writes shares
- Billing routes → Billing service: settles charges
- Billing routes → Payment gateway: creates checkout
- Payment gateway → Payment provider: uses provider
- Billing service → Application data: updates wallet
- Admin console → FastAPI app: calls API
- Admin routes → Application data: reads and updates
- Traffic tracking → Application data: records views