Skip to content

bugfix(KLEF-91): Updated documentation for projects and billing to match the current implementation #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
isaacwallace123 merged 1 commit into from
Feb 16, 2026
Merged

bugfix(KLEF-91): Updated documentation for projects and billing to match the current implementation #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 3 additions & 6 deletions docs/Billing/BillingUseCase.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ skinparam usecase {
actor "Developer" as AuthUser #silver
actor "Project Owner" as Owner #lightblue
actor "Collaborator" as Collab #lightgreen
actor "Payment Gateway" as Payment #green
actor "Stripe" as Payment #green
actor "Time" as TimeActor #gray

Owner -|> AuthUser
Expand All @@ -20,10 +20,9 @@ Collab -|> AuthUser
rectangle "Kleff Hosting Platform" {

package "Billing" #B3E5FC {
usecase "UC-40: View Billing Dashboard" as UC40
usecase "UC-40: View Bills for Project" as UC40
usecase "UC-41: Pay Invoice" as UC41
usecase "UC-42: Download Invoice" as UC42
usecase "UC-43: Update Payment Method" as UC43
usecase "UC-43: View Invoice" as UC43
usecase "UC-44: View Bill History" as UC44

' NEW Automatic time-based billing use cases
Expand All @@ -36,7 +35,6 @@ rectangle "Kleff Hosting Platform" {
AuthUser -- UC40

Owner -- UC41
Owner -- UC42
Owner -- UC43

' ==== Time-based System Triggers ====
Expand All @@ -47,7 +45,6 @@ TimeActor ..> UC46 : <<system trigger>>\nReminder schedule
UC41 ..> Payment : <<system trigger>>\nPayment processing

' ==== EXTENDS ====
UC42 .> UC41 : <<extends>>
UC43 .> UC41 : <<extends>>

' ==== INCLUDES ====
Expand Down
20 changes: 5 additions & 15 deletions docs/Billing/C4L3-Billing.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,8 @@ Container(spa, "Kleff Dashboard (SPA)", "TypeScript, React", "Frontend for viewi
Container(obs_svc, "Observability Service", "Go", "Provides aggregated usage per project/container.")
Container(identity_svc, "Identity & Access Service", "Java/Go", "Provides user and tenant information.")
ContainerDb(project_db, "project-db", "PostgreSQL", "Stores project metadata used in billing descriptions.")
ContainerDb(billing_db, "billing-db", "PostgreSQL", "Stores UsageRecords, ReservedAllocations, and Invoices.")
System_Ext(payment_gateway, "Payment Gateway", "Stripe/PayPal", "Captures payments and handles billing events.")
System_Ext(email_service, "Email Service", "SMTP / Email API", "Sends invoice and payment emails.")
ContainerDb(billing_db, "billing-db", "PostgreSQL", "Stores Invoices, Prices and reserved allocation information.")
System_Ext(payment_gateway, "Payment Gateway", "Stripe", "Captures payments and handles billing events.")

' ==== Billing Service Boundary ====
Container_Boundary(billing_svc, "Billing Service") {
Expand All @@ -25,21 +24,20 @@ Container_Boundary(billing_svc, "Billing Service") {
Component(payment_webhook_api, "Payment Webhook Controller", "Webhook Endpoint", "Receives payment events (succeeded, failed, refunded) from Payment Gateway.")

' ---- Application / Service Layer ----
Component(usage_agg_svc, "Usage Aggregation Service", "Application Service", "Pulls usage data from Observability and maps it to billing UsageRecords per project/tenant.")

Component(billing_app_svc, "Billing Application Service", "Application Service", "Calculates charges based on PricingModel, creates Invoice aggregates, and applies discounts/credits.")

Component(payment_app_svc, "Payment Application Service", "Application Service", "Coordinates payment intents/charges with the Payment Gateway and updates invoice status based on webhooks.")

' ---- Domain Layer ----
Component(usage_domain, "UsageRecord & ReservedAllocation Domain Model", "Domain Model", "Represents measured usage and reserved capacity for billing (CPU_HOURS, CONTAINER_HOURS, etc.).")
Component(usage_domain, "Prices & ReservedAllocation Domain Model", "Domain Model", "Represents prices for metrics and reserved capacity for billing (CPU_HOURS, CONTAINER_HOURS, etc.).")

Component(invoice_domain, "Invoice Aggregate", "Domain Model", "Represents an invoice with multiple items, totals, and status transitions (DRAFT, ISSUED, PAID).")

Component(domain_events, "Billing Domain Event Publisher", "Domain Service", "Publishes events (InvoiceIssued, InvoicePaid, PaymentFailed) for notifications/audit.")

' ---- Infrastructure / Adapters ----
Component(billing_repo, "BillingRepository", "Repository Adapter", "Persists and reads UsageRecords, ReservedAllocations, and Invoices from billing-db.")
Component(billing_repo, "BillingRepository", "Repository Adapter", "Persists and reads Invoices from billing-db.")

Component(obs_client, "ObservabilityServiceClient", "Integration Adapter", "Retrieves aggregated usage metrics per project/container from Observability Service.")

Expand All @@ -49,7 +47,6 @@ Container_Boundary(billing_svc, "Billing Service") {

Component(payment_gateway_adapter, "PaymentGatewayAdapter", "Integration Adapter", "Creates payment intents, charges customers, and validates signatures on webhooks.")

Component(email_adapter, "BillingEmailAdapter", "Integration Adapter", "Sends invoice and payment status emails via Email Service.")
}

' ==== Relationships: SPA -> Billing Service ====
Expand All @@ -60,36 +57,29 @@ Rel(spa, invoice_api, "Views and downloads invoices via /api/invoices/*", "JSON/
Rel(payment_gateway, payment_webhook_api, "Sends payment events", "HTTPS/Webhook")

' ==== API -> Application Layer ====
Rel(billing_api, usage_agg_svc, "Invokes for usage summaries", "Method calls")
Rel(billing_api, billing_app_svc, "May trigger invoice generation (admin flows)", "Method calls")
Rel(invoice_api, billing_app_svc, "Loads invoices for viewing", "Method calls")
Rel(payment_webhook_api, payment_app_svc, "Invokes", "Method calls")

' ==== Application -> Domain & Adapters ====
Rel(usage_agg_svc, obs_client, "Fetches aggregated usage per project/container", "JSON/REST/HTTPS")
Rel(usage_agg_svc, usage_domain, "Maps raw usage → UsageRecord domain objects", "Method calls")
Rel(usage_agg_svc, billing_repo, "Persists UsageRecords", "Repository API")

Rel(billing_app_svc, billing_repo, "Reads UsageRecords & ReservedAllocations", "Repository API")
Rel(billing_app_svc, usage_domain, "Applies usage & pricing rules", "Method calls")
Rel(billing_app_svc, invoice_domain, "Creates/updates Invoice aggregates", "Method calls")
Rel(billing_app_svc, project_reader, "Enriches line-items with project metadata", "Data access")
Rel(billing_app_svc, identity_client, "Resolves billing contact & tenant info", "JSON/REST/HTTPS")
Rel(billing_app_svc, domain_events, "Publishes InvoiceIssued events", "Event dispatch")
Rel(billing_app_svc, email_adapter, "Sends invoice emails", "Send email")

Rel(payment_app_svc, billing_repo, "Updates Invoice status based on payments", "Repository API")
Rel(payment_app_svc, invoice_domain, "Applies payment-related status transitions", "Method calls")
Rel(payment_app_svc, payment_gateway_adapter, "Creates charges / validates webhook signatures", "HTTPS/API")
Rel(payment_app_svc, domain_events, "Publishes InvoicePaid/PaymentFailed events", "Event dispatch")
Rel(payment_app_svc, email_adapter, "Sends payment success/failure emails", "Send email")

Rel(billing_app_svc, obs_client, "Reads aggregated usage per project/container", "Repository API")
' ==== Adapters -> External Systems ====
Rel(billing_repo, billing_db, "Reads/Writes UsageRecords, ReservedAllocations, Invoices", "SQL")
Rel(obs_client, obs_svc, "Reads aggregated usage per project/container", "JSON/REST/HTTPS")
Rel(project_reader, project_db, "Reads project metadata", "SQL (read-only)")
Rel(identity_client, identity_svc, "Reads user/tenant info", "JSON/REST/HTTPS")
Rel(payment_gateway_adapter, payment_gateway, "Creates payment intents & charges; receives webhook payloads", "HTTPS/API")
Rel(email_adapter, email_service, "Sends billing-related emails", "SMTP/HTTPS")

@enduml
6 changes: 1 addition & 5 deletions docs/Project/C4L3-Project.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,14 +34,13 @@ Container_Boundary(project_svc, "Project Management Service") {

Component(collab_domain, "ProjectCollaborator Entity", "Domain Model", "Represents membership of a user in a project with a role and fine-grained permissions.")

Component(domain_events, "Project Domain Event Publisher", "Domain Service", "Raises events (ProjectCreated, CollaboratorInvited, CollaboratorRoleChanged) for notifications and audit.")

' ---- Infrastructure / Adapters ----
Component(project_repo, "ProjectRepository", "Repository Adapter", "Persists and retrieves Project aggregates and collaborator entities from project-db.")

Component(identity_client, "IdentityServiceClient", "Integration Adapter", "Looks up users by ID/email and validates their existence in the Identity & Access BC.")

Component(email_adapter, "ProjectEmailAdapter", "Integration Adapter", "Sends collaboration invitations and project notifications via Email Service.")
Component(email_adapter, "ProjectNotification", "Integration Adapter", "Sends collaboration invitations and project notifications via the application")

Component(git_integration, "GitIntegrationAdapter", "Integration Adapter", "Configures webhooks and repository metadata on the Git Provider when projects are created/updated.")
}
Expand All @@ -64,21 +63,18 @@ Rel(project_perm_api, project_permission_svc, "Invokes", "Method calls")
Rel(project_app_svc, project_repo, "Creates/updates Projects & webhook config", "Repository API")
Rel(project_app_svc, project_domain, "Applies domain logic", "Method calls")
Rel(project_app_svc, git_integration, "Configures webhooks on repository", "HTTPS/API")
Rel(project_app_svc, domain_events, "Publishes ProjectCreated/Updated events", "Event dispatch")

Rel(collab_app_svc, project_repo, "Updates collaborator roles & permissions", "Repository API")
Rel(collab_app_svc, collab_domain, "Applies collaboration domain rules", "Method calls")
Rel(collab_app_svc, identity_client, "Resolves invitee user IDs", "JSON/REST/HTTPS")
Rel(collab_app_svc, email_adapter, "Sends invitations to collaborators", "Send email")
Rel(collab_app_svc, domain_events, "Publishes CollaboratorInvited/RoleChanged events", "Event dispatch")

Rel(project_permission_svc, project_repo, "Reads project collaborators & permissions", "Repository API")
Rel(project_permission_svc, collab_domain, "Evaluates project-level permissions", "Method calls")

' ==== Adapters -> External Systems ====
Rel(project_repo, project_db, "Reads/Writes Projects & Collaborators", "SQL")
Rel(identity_client, identity_svc, "Reads User info from Identity & Access BC", "JSON/REST/HTTPS")
Rel(email_adapter, email_service, "Sends invitation emails", "SMTP/HTTPS")
Rel(git_integration, git_provider, "Configures webhooks & repo metadata", "HTTPS/Git API")

' ==== Controller Endpoints ====
Expand Down