# alt-f6/edtech-billing-core architecture

> Architecture diagram of the GitHub repository alt-f6/edtech-billing-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alt-f6/edtech-billing-core
- Repository: https://github.com/alt-f6/edtech-billing-core

## Overview

This is a framework-free TypeScript core for EdTech billing, payment webhooks, and enumeration-resistant login. Staff attendance changes drive race-safe lesson charges and reversals; payment notifications are rate-limited, authenticated, re-verified with the provider, checked against payment intent data, then credited idempotently. Login reserves atomic limits before an enumeration-safe password check. The graph reflects README-documented capabilities where source was not sampled; those links cite the README, and the database schema is represented by the migration.

Main entry points: [`src/payments/webhook.handler.ts`](https://github.com/alt-f6/edtech-billing-core/blob/main/src/payments/webhook.handler.ts) (Webhook pipeline), [`src/auth/login-rate-limit.ts`](https://github.com/alt-f6/edtech-billing-core/blob/main/src/auth/login-rate-limit.ts) (Login flow and limits), [`src/billing/billing.service.ts`](https://github.com/alt-f6/edtech-billing-core/blob/main/src/billing/billing.service.ts) (Attendance billing), [`src/db.ts`](https://github.com/alt-f6/edtech-billing-core/blob/main/src/db.ts) (Pool and transactions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_billing["Lesson billing"]
  node_billing_service["Attendance billing<br/>[billing.service.ts]"]
  node_schema["Billing schema<br/>[001_init.sql]"]
end

subgraph group_payments["Payment webhooks"]
  node_webhook_handler["Webhook pipeline<br/>[webhook.handler.ts]"]
  node_webhook_auth["Webhook authentication<br/>[webhook-auth.ts]"]
  node_payment_provider["Provider client and validation<br/>[provider.ts]"]
  node_payment_credit["Idempotent payment credit<br/>[webhook.handler.ts]"]
end

subgraph group_auth["Login security"]
  node_login["Login flow and limits"]
  node_email["Email normalization<br/>[email.ts]"]
  node_password["Enumeration-safe password check<br/>[password.ts]"]
end

subgraph group_shared["Shared infrastructure"]
  node_money["Exact money parsing<br/>[money.ts]"]
  node_rate_limit["Postgres rate limiter<br/>[rate-limit.ts]"]
  node_db["Pool and transactions<br/>[db.ts]"]
  node_errors["Typed billing errors<br/>[errors.ts]"]
end

node_staff(("School staff"))
node_postgres[("PostgreSQL")]
node_webhook_sender(("Payment provider webhook"))
node_yookassa["YooKassa API"]
node_login_user(("Login user"))

node_staff -->|"marks lessons"| node_billing_service
node_billing_service -->|"locks and writes"| node_postgres
node_schema -->|"defines constraints"| node_postgres
node_webhook_sender -->|"submits notification"| node_webhook_handler
node_webhook_handler -->|"checks request limit"| node_rate_limit
node_webhook_handler -->|"checks secret and IP"| node_webhook_auth
node_webhook_handler -->|"fetches and parses payment"| node_payment_provider
node_payment_provider -->|"fetches payment"| node_yookassa
node_webhook_handler -->|"reads payment intent"| node_postgres
node_webhook_handler -->|"parses provider amount"| node_money
node_webhook_handler -->|"credits verified payment"| node_payment_credit
node_payment_credit -->|"writes idempotent ledger row"| node_postgres
node_login_user -->|"submits credentials"| node_login
node_login -->|"normalizes email"| node_email
node_login -->|"checks password"| node_password
node_login -->|"reserves and clears attempts"| node_postgres
node_rate_limit -->|"updates limit buckets"| node_postgres
node_billing_service -->|"uses transactions"| node_db
node_webhook_handler -->|"uses transactions and IP hash"| node_db
node_login -->|"uses transactions and IP hash"| node_db
node_db -->|"connects and transacts"| node_postgres
node_billing_service -->|"raises typed errors"| node_errors

click node_billing_service "https://github.com/alt-f6/edtech-billing-core/blob/main/src/billing/billing.service.ts"
click node_schema "https://github.com/alt-f6/edtech-billing-core/blob/main/migrations/001_init.sql"
click node_webhook_handler "https://github.com/alt-f6/edtech-billing-core/blob/main/src/payments/webhook.handler.ts"
click node_webhook_auth "https://github.com/alt-f6/edtech-billing-core/blob/main/src/payments/webhook-auth.ts"
click node_payment_provider "https://github.com/alt-f6/edtech-billing-core/blob/main/src/payments/provider.ts"
click node_payment_credit "https://github.com/alt-f6/edtech-billing-core/blob/main/src/payments/webhook.handler.ts"
click node_money "https://github.com/alt-f6/edtech-billing-core/blob/main/src/money.ts"
click node_rate_limit "https://github.com/alt-f6/edtech-billing-core/blob/main/src/rate-limit/rate-limit.ts"
click node_login "https://github.com/alt-f6/edtech-billing-core/blob/main/src/auth/login-rate-limit.ts"
click node_email "https://github.com/alt-f6/edtech-billing-core/blob/main/src/auth/email.ts"
click node_password "https://github.com/alt-f6/edtech-billing-core/blob/main/src/auth/password.ts"
click node_db "https://github.com/alt-f6/edtech-billing-core/blob/main/src/db.ts"
click node_errors "https://github.com/alt-f6/edtech-billing-core/blob/main/src/errors.ts"

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_billing_service,node_schema,node_login_user toneBlue
class node_webhook_handler,node_webhook_auth,node_payment_provider,node_payment_credit,node_postgres toneAmber
class node_login,node_email,node_password,node_webhook_sender,node_yookassa toneMint
class node_money,node_rate_limit,node_db,node_errors toneRose
class node_staff toneIndigo
```

## Components

### Lesson billing

- [Attendance billing](https://github.com/alt-f6/edtech-billing-core/blob/main/src/billing/billing.service.ts): `src/billing/billing.service.ts`
- [Billing schema](https://github.com/alt-f6/edtech-billing-core/blob/main/migrations/001_init.sql): `migrations/001_init.sql`

### Payment webhooks

- [Webhook pipeline](https://github.com/alt-f6/edtech-billing-core/blob/main/src/payments/webhook.handler.ts): `src/payments/webhook.handler.ts`
- [Webhook authentication](https://github.com/alt-f6/edtech-billing-core/blob/main/src/payments/webhook-auth.ts): `src/payments/webhook-auth.ts`
- [Provider client and validation](https://github.com/alt-f6/edtech-billing-core/blob/main/src/payments/provider.ts): `src/payments/provider.ts`
- [Idempotent payment credit](https://github.com/alt-f6/edtech-billing-core/blob/main/src/payments/webhook.handler.ts): `src/payments/webhook.handler.ts`

### Login security

- [Login flow and limits](https://github.com/alt-f6/edtech-billing-core/blob/main/src/auth/login-rate-limit.ts): `src/auth/login-rate-limit.ts`
- [Email normalization](https://github.com/alt-f6/edtech-billing-core/blob/main/src/auth/email.ts): `src/auth/email.ts`
- [Enumeration-safe password check](https://github.com/alt-f6/edtech-billing-core/blob/main/src/auth/password.ts): `src/auth/password.ts`

### Shared infrastructure

- [Exact money parsing](https://github.com/alt-f6/edtech-billing-core/blob/main/src/money.ts): `src/money.ts`
- [Postgres rate limiter](https://github.com/alt-f6/edtech-billing-core/blob/main/src/rate-limit/rate-limit.ts): `src/rate-limit/rate-limit.ts`
- [Pool and transactions](https://github.com/alt-f6/edtech-billing-core/blob/main/src/db.ts): `src/db.ts`
- [Typed billing errors](https://github.com/alt-f6/edtech-billing-core/blob/main/src/errors.ts): `src/errors.ts`

### Other components

- **School staff**
- **PostgreSQL**
- **Payment provider webhook**
- **YooKassa API**
- **Login user**

## Connections

- School staff → Attendance billing: marks lessons (evidence: `README.md`)
- Attendance billing → PostgreSQL: locks and writes (evidence: `src/billing/billing.service.ts`)
- Billing schema → PostgreSQL: defines constraints (evidence: `README.md`)
- Payment provider webhook → Webhook pipeline: submits notification (evidence: `README.md`)
- Webhook pipeline → Postgres rate limiter: checks request limit (evidence: `src/payments/webhook.handler.ts`)
- Webhook pipeline → Webhook authentication: checks secret and IP (evidence: `src/payments/webhook.handler.ts`)
- Webhook pipeline → Provider client and validation: fetches and parses payment (evidence: `src/payments/webhook.handler.ts`)
- Provider client and validation → YooKassa API: fetches payment (evidence: `README.md`)
- Webhook pipeline → PostgreSQL: reads payment intent (evidence: `src/payments/webhook.handler.ts`)
- Webhook pipeline → Exact money parsing: parses provider amount (evidence: `src/payments/webhook.handler.ts`)
- Webhook pipeline → Idempotent payment credit: credits verified payment (evidence: `src/payments/webhook.handler.ts`)
- Idempotent payment credit → PostgreSQL: writes idempotent ledger row (evidence: `src/payments/webhook.handler.ts`)
- Login user → Login flow and limits: submits credentials (evidence: `README.md`)
- Login flow and limits → Email normalization: normalizes email (evidence: `src/auth/login-rate-limit.ts`)
- Login flow and limits → Enumeration-safe password check: checks password (evidence: `README.md`)
- Login flow and limits → PostgreSQL: reserves and clears attempts (evidence: `src/auth/login-rate-limit.ts`)
- Postgres rate limiter → PostgreSQL: updates limit buckets (evidence: `src/rate-limit/rate-limit.ts`)
- Attendance billing → Pool and transactions: uses transactions (evidence: `src/billing/billing.service.ts`)
- Webhook pipeline → Pool and transactions: uses transactions and IP hash (evidence: `src/payments/webhook.handler.ts`)
- Login flow and limits → Pool and transactions: uses transactions and IP hash (evidence: `src/auth/login-rate-limit.ts`)
- Pool and transactions → PostgreSQL: connects and transacts (evidence: `README.md`)
- Attendance billing → Typed billing errors: raises typed errors (evidence: `src/billing/billing.service.ts`)
