# avinashcreates/billsphere architecture

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

- Interactive diagram: https://gitdiagram.com/avinashcreates/billsphere
- Repository: https://github.com/avinashcreates/billsphere

## Overview

BillSphere is a subscription-billing platform with customer and administrator experiences. Customers register, choose a plan, subscribe, pay, and receive invoices and billing updates; recurring billing and failed-payment recovery run in the background. The graph shows the documented lifecycle and the sampled API, billing, payment, persistence, and worker layers. Several service-to-route and browser-to-API connections are not established by the excerpts, so they are omitted rather than inferred.

Main entry points: [`INFY/backend/app/api/v1/router.py`](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/router.py) (Versioned API router), [`INFY/backend/app/services/billing_cycle_service.py`](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/billing_cycle_service.py) (Recurring billing), [`INFY/backend/app/services/payment_service.py`](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/payment_service.py) (Payment processing), [`INFY/frontend/src/App.tsx`](https://github.com/avinashcreates/billsphere/blob/main/INFY/frontend/src/App.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experiences"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_customer_pages["Customer billing pages"]
  node_admin_pages["Admin dashboard<br/>[AdminDashboard.tsx]"]
  node_frontend_auth["Frontend authentication<br/>[AuthContext.tsx]"]
  node_frontend_api["Frontend API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_app_entry["FastAPI application<br/>[main.py]"]
  node_api_router["Versioned API router<br/>[router.py]"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
  node_subscriptions_api["Subscription endpoints<br/>[subscriptions.py]"]
  node_billing_api["Billing endpoints<br/>[billing_cycles.py]"]
  node_payment_api["Payment endpoints<br/>[payments.py]"]
  node_analytics_api["Analytics and reporting<br/>[analytics.py]"]
  node_notifications_api["Notifications<br/>[notifications.py]"]
  node_webhooks_api["Webhook endpoints<br/>[webhooks.py]"]
end

subgraph group_billing["Billing operations"]
  node_subscription_service["Subscription lifecycle"]
  node_cycle_service["Recurring billing"]
  node_payment_service["Payment processing<br/>[payment_service.py]"]
  node_invoice_service["Invoice generation<br/>[invoice_service.py]"]
  node_retry_service["Failed-payment recovery<br/>[payment_service.py]"]
end

subgraph group_platform["Persistence and background"]
  node_domain_models["Billing records"]
  node_database[("PostgreSQL")]
  node_worker_tasks["Background billing tasks<br/>[tasks.py]"]
end

node_customer(("Customer"))
node_administrator(("Administrator"))

node_customer -->|"uses"| node_webapp
node_administrator -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_customer_pages
node_webapp -->|"routes to"| node_admin_pages
node_webapp -.->|"provides access"| node_frontend_auth
node_customer_pages -.->|"requests data"| node_frontend_api
node_admin_pages -.->|"requests data"| node_frontend_api
node_frontend_api -.->|"calls API"| node_app_entry
node_app_entry -->|"mounts routes"| node_api_router
node_api_router -->|"registers"| node_subscriptions_api
node_api_router -->|"registers"| node_billing_api
node_api_router -->|"registers"| node_payment_api
node_api_router -->|"registers"| node_analytics_api
node_api_router -->|"registers"| node_notifications_api
node_api_router -->|"registers"| node_webhooks_api
node_subscription_service -->|"delegates billing"| node_cycle_service
node_subscription_service -->|"calls payment"| node_payment_service
node_cycle_service -->|"uses invoicing"| node_invoice_service
node_payment_service -->|"uses invoices"| node_invoice_service
node_cycle_service -->|"reads and writes"| node_domain_models
node_payment_service -->|"reads and writes"| node_domain_models
node_domain_models -->|"persists records"| node_database
node_worker_tasks -->|"runs billing"| node_cycle_service
node_worker_tasks -->|"runs retries"| node_payment_service
node_customer -->|"selects plan"| node_subscriptions_api
node_subscriptions_api -.->|"handles lifecycle"| node_subscription_service
node_billing_api -.->|"handles cycles"| node_cycle_service
node_payment_api -.->|"handles payments"| node_payment_service
node_cycle_service -->|"generates invoices"| node_invoice_service
node_payment_service -->|"schedules recovery"| node_retry_service

click node_webapp "https://github.com/avinashcreates/billsphere/blob/main/INFY/frontend/src/App.tsx"
click node_customer_pages "https://github.com/avinashcreates/billsphere/tree/main/INFY/frontend/src/pages"
click node_admin_pages "https://github.com/avinashcreates/billsphere/blob/main/INFY/frontend/src/pages/AdminDashboard.tsx"
click node_frontend_auth "https://github.com/avinashcreates/billsphere/blob/main/INFY/frontend/src/contexts/AuthContext.tsx"
click node_frontend_api "https://github.com/avinashcreates/billsphere/blob/main/INFY/frontend/src/services/api.ts"
click node_app_entry "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/main.py"
click node_api_router "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/router.py"
click node_auth_service "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/auth_service.py"
click node_subscriptions_api "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/subscriptions.py"
click node_billing_api "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/billing_cycles.py"
click node_payment_api "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/payments.py"
click node_subscription_service "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/subscription_service.py"
click node_cycle_service "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/billing_cycle_service.py"
click node_payment_service "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/payment_service.py"
click node_invoice_service "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/invoice_service.py"
click node_retry_service "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/payment_service.py"
click node_domain_models "https://github.com/avinashcreates/billsphere/tree/main/INFY/backend/app/models"
click node_worker_tasks "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/workers/tasks.py"
click node_analytics_api "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/analytics.py"
click node_notifications_api "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/notifications.py"
click node_webhooks_api "https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/webhooks.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_webapp,node_customer_pages,node_admin_pages,node_frontend_auth,node_frontend_api toneBlue
class node_app_entry,node_api_router,node_auth_service,node_subscriptions_api,node_billing_api,node_payment_api,node_analytics_api,node_notifications_api,node_webhooks_api toneAmber
class node_subscription_service,node_cycle_service,node_payment_service,node_invoice_service,node_retry_service toneMint
class node_domain_models,node_database,node_worker_tasks toneRose
class node_customer,node_administrator toneIndigo
```

## Components

### User experiences

- [Web application](https://github.com/avinashcreates/billsphere/blob/main/INFY/frontend/src/App.tsx): `INFY/frontend/src/App.tsx`
- [Customer billing pages](https://github.com/avinashcreates/billsphere/tree/main/INFY/frontend/src/pages): `INFY/frontend/src/pages`
- [Admin dashboard](https://github.com/avinashcreates/billsphere/blob/main/INFY/frontend/src/pages/AdminDashboard.tsx): `INFY/frontend/src/pages/AdminDashboard.tsx`
- [Frontend authentication](https://github.com/avinashcreates/billsphere/blob/main/INFY/frontend/src/contexts/AuthContext.tsx): `INFY/frontend/src/contexts/AuthContext.tsx`
- [Frontend API client](https://github.com/avinashcreates/billsphere/blob/main/INFY/frontend/src/services/api.ts): `INFY/frontend/src/services/api.ts`

### API and access

- [FastAPI application](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/main.py): `INFY/backend/app/main.py`
- [Versioned API router](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/router.py): `INFY/backend/app/api/v1/router.py`
- [Authentication service](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/auth_service.py): `INFY/backend/app/services/auth_service.py`
- [Subscription endpoints](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/subscriptions.py): `INFY/backend/app/api/v1/subscriptions.py`
- [Billing endpoints](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/billing_cycles.py): `INFY/backend/app/api/v1/billing_cycles.py`
- [Payment endpoints](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/payments.py): `INFY/backend/app/api/v1/payments.py`
- [Analytics and reporting](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/analytics.py): `INFY/backend/app/api/v1/analytics.py`
- [Notifications](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/notifications.py): `INFY/backend/app/api/v1/notifications.py`
- [Webhook endpoints](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/api/v1/webhooks.py): `INFY/backend/app/api/v1/webhooks.py`

### Billing operations

- [Subscription lifecycle](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/subscription_service.py): `INFY/backend/app/services/subscription_service.py`
- [Recurring billing](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/billing_cycle_service.py): `INFY/backend/app/services/billing_cycle_service.py`
- [Payment processing](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/payment_service.py): `INFY/backend/app/services/payment_service.py`
- [Invoice generation](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/invoice_service.py): `INFY/backend/app/services/invoice_service.py`
- [Failed-payment recovery](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/services/payment_service.py): `INFY/backend/app/services/payment_service.py`

### Persistence and background

- [Billing records](https://github.com/avinashcreates/billsphere/tree/main/INFY/backend/app/models): `INFY/backend/app/models`
- **PostgreSQL**
- [Background billing tasks](https://github.com/avinashcreates/billsphere/blob/main/INFY/backend/app/workers/tasks.py): `INFY/backend/app/workers/tasks.py`

### Other components

- **Customer**
- **Administrator**

## Connections

- Customer → Web application: uses (evidence: `README.md`)
- Administrator → Web application: uses (evidence: `README.md`)
- Web application → Customer billing pages: routes to (evidence: `INFY/frontend/src/App.tsx`)
- Web application → Admin dashboard: routes to (evidence: `INFY/frontend/src/App.tsx`)
- Web application → Frontend authentication: provides access
- Customer billing pages → Frontend API client: requests data
- Admin dashboard → Frontend API client: requests data
- Frontend API client → FastAPI application: calls API
- FastAPI application → Versioned API router: mounts routes (evidence: `INFY/backend/app/main.py`)
- Versioned API router → Subscription endpoints: registers (evidence: `INFY/backend/app/api/v1/router.py`)
- Versioned API router → Billing endpoints: registers (evidence: `INFY/backend/app/api/v1/router.py`)
- Versioned API router → Payment endpoints: registers (evidence: `INFY/backend/app/api/v1/router.py`)
- Versioned API router → Analytics and reporting: registers (evidence: `INFY/backend/app/api/v1/router.py`)
- Versioned API router → Notifications: registers (evidence: `INFY/backend/app/api/v1/router.py`)
- Versioned API router → Webhook endpoints: registers (evidence: `INFY/backend/app/api/v1/router.py`)
- Subscription lifecycle → Recurring billing: delegates billing (evidence: `INFY/backend/app/services/subscription_service.py`)
- Subscription lifecycle → Payment processing: calls payment (evidence: `INFY/backend/app/services/subscription_service.py`)
- Recurring billing → Invoice generation: uses invoicing (evidence: `INFY/backend/app/services/billing_cycle_service.py`)
- Payment processing → Invoice generation: uses invoices (evidence: `INFY/backend/app/services/payment_service.py`)
- Recurring billing → Billing records: reads and writes (evidence: `INFY/backend/app/services/billing_cycle_service.py`)
- Payment processing → Billing records: reads and writes (evidence: `INFY/backend/app/services/payment_service.py`)
- Billing records → PostgreSQL: persists records
- Background billing tasks → Recurring billing: runs billing (evidence: `INFY/backend/app/workers/tasks.py`)
- Background billing tasks → Payment processing: runs retries (evidence: `INFY/backend/app/workers/tasks.py`)
- Customer → Subscription endpoints: selects plan (evidence: `README.md`)
- Subscription endpoints → Subscription lifecycle: handles lifecycle
- Billing endpoints → Recurring billing: handles cycles
- Payment endpoints → Payment processing: handles payments
- Recurring billing → Invoice generation: generates invoices (evidence: `README.md`)
- Payment processing → Failed-payment recovery: schedules recovery (evidence: `README.md`)