From 40bf884737ffda0ad07c89750093f7ce0370e83b Mon Sep 17 00:00:00 2001 From: AlexRemiNoel Date: Fri, 13 Feb 2026 09:53:35 -0500 Subject: [PATCH] updated documentation for projects and billing to match the current implementation --- docs/Billing/BillingUseCase.puml | 9 +++------ docs/Billing/C4L3-Billing.puml | 20 +++++--------------- docs/Project/C4L3-Project.puml | 6 +----- 3 files changed, 9 insertions(+), 26 deletions(-) diff --git a/docs/Billing/BillingUseCase.puml b/docs/Billing/BillingUseCase.puml index 64f0e20..3d813c8 100644 --- a/docs/Billing/BillingUseCase.puml +++ b/docs/Billing/BillingUseCase.puml @@ -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 @@ -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 @@ -36,7 +35,6 @@ rectangle "Kleff Hosting Platform" { AuthUser -- UC40 Owner -- UC41 -Owner -- UC42 Owner -- UC43 ' ==== Time-based System Triggers ==== @@ -47,7 +45,6 @@ TimeActor ..> UC46 : <>\nReminder schedule UC41 ..> Payment : <>\nPayment processing ' ==== EXTENDS ==== -UC42 .> UC41 : <> UC43 .> UC41 : <> ' ==== INCLUDES ==== diff --git a/docs/Billing/C4L3-Billing.puml b/docs/Billing/C4L3-Billing.puml index a42e300..0843e08 100644 --- a/docs/Billing/C4L3-Billing.puml +++ b/docs/Billing/C4L3-Billing.puml @@ -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") { @@ -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.") @@ -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 ==== @@ -60,15 +57,11 @@ 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") @@ -76,20 +69,17 @@ Rel(billing_app_svc, invoice_domain, "Creates/updates Invoice aggregates", "Meth 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 diff --git a/docs/Project/C4L3-Project.puml b/docs/Project/C4L3-Project.puml index 4199519..984fb8f 100644 --- a/docs/Project/C4L3-Project.puml +++ b/docs/Project/C4L3-Project.puml @@ -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.") } @@ -64,13 +63,11 @@ 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") @@ -78,7 +75,6 @@ Rel(project_permission_svc, collab_domain, "Evaluates project-level permissions" ' ==== 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 ====