# yusufdupsc1/clientflow-pro architecture

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

- Interactive diagram: https://gitdiagram.com/yusufdupsc1/clientflow-pro
- Repository: https://github.com/yusufdupsc1/clientflow-pro

## Overview

1. **Overall shape**
   - This is a single Laravel monolith for a multi-tenant CRM/billing product.
   - It combines server-rendered Blade UI, JSON APIs, public payment pages, webhook handling, background jobs, and console automation in one codebase.

2. **Primary business boundaries**
   - The core domain is split into **Organizations**, **Clients**, **Projects**, **Invoices**, **Payments**, and **Invitations**.
   - Supporting domain objects include **Roles/Permissions**, **Audit Logs**, **Files**, **Webhook records**, and **Stripe webhook events**.
   - Most domain logic is organized around these entities rather than around UI screens.

3. **Tenant isolation model**
   - Organization scoping is a central architectural boundary.
   - The app uses a tenant context (`app/Support/Tenancy/Tenant.php`), a tenancy-aware model concern (`BelongsToOrganization`), and request middleware (`EnsureOrganizationSelected`) to prevent cross-organization access.
   - Many controllers, policies, and tests exist specifically to enforce this isolation.

4. **Authorization and access control**
   - Access is layered: authentication first, then organization selection, then policy-based authorization.
   - Roles and permissions are stored in the database and enforced through policies such as `ClientPolicy`, `InvoicePolicy`, `PaymentPolicy`, `ProjectPolicy`, and `OrganizationPolicy`.
   - The app supports per-organization membership and role changes, with notifications for role-related events.

5. **Main request surfaces**
   - There are three major HTTP surfaces:
     - **Web UI** under `app/Http/Controllers/Web` for dashboard, settings, CRUD, exports, and audit views.
     - **API** under `app/Http/Controllers/Api` for clients, invoices, payments, projects, invitations, audit, and token management.
     - **Public/guest flows** for client portal and invoice payment pages.
   - Auth routes are separated under `routes/auth.php`; general web routes live in `routes/web.php`.

6. **Billing and invoicing workflow**
   - Billing behavior is split between controllers and action classes in `app/Actions/Billing`.
   - The invoice lifecycle includes draft, sent, overdue, paid, and void states, with dedicated actions for creating, updating, sending, posting payments, refunds, and voiding.
   - Invoice PDFs are generated through `InvoicePdfService`, and invoice presentation includes branding, tax, discounts, and downloadable PDF output.

7. **Stripe payment integration**
   - Stripe is the external payment boundary.
   - Users can configure Stripe per organization or via environment settings; organization settings take precedence.
   - Public invoice payment links (`/pay/{public_hash}`) initiate checkout, while `POST /stripe/webhook` receives Stripe events.
   - Webhook processing is asynchronous: the webhook controller hands off to `ProcessStripeWebhook`, which updates invoices/payments and can trigger receipts or state changes.

8. **Asynchronous and scheduled work**
   - Queue jobs handle longer-running or external tasks: CSV exports, webhook processing, and other deferred work.
   - Console commands cover operational workflows like demo seeding, overdue invoice marking, overdue reminder sending, currency repair, and mail testing.
   - This indicates the app relies on background processing for billing notifications, exports, and payment event reconciliation.

9. **Presentation layer**
   - The UI is Blade-based with a custom layout/component system in `resources/views`.
   - Frontend assets are built with Vite, Tailwind, and a small amount of JavaScript.
   - Separate view groups exist for auth, dashboard, clients, projects, invoices, payments, organization settings, portal/payment pages, and reusable UI components.

10. **Data persistence**
   - The app uses a relational database with migrations defining the full schema for tenants, billing, access control, invites, webhooks, tokens, and logs.
   - File uploads and generated artifacts are stored under `storage`, with a public storage link used for accessible assets such as branding files or exported documents.
   - Audit/activity tracking is first-class, with dedicated tables and UI views for review and export.

11. **API and SDK boundary**
   - Sanctum-backed personal access tokens expose the API to external clients.
   - `app/Http/Resources` standardize JSON output, and `sdk/js` plus `sdk/php` suggest generated or packaged client libraries for consuming the API.
   - API docs are exposed through the web layer, making the API a documented integration surface rather than an internal-only interface.

12. **Operational and deployment concerns**
   - The repo includes Docker, Nginx, CI/CD workflows, and a Render deployment config, so it is designed for containerized deployment.
   - Runtime dependencies include PHP, SQLite by default, Node for asset builds, and queue/scheduler workers for full functionality.
   - Tests are extensive and organized around tenancy, auth, billing workflow, Stripe, APIs, webhook dispatch, and role enforcement, reflecting the system’s key architectural risks.

Main entry points: [`app/Models`](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Models) (Domain models), [`routes/web.php`](https://github.com/yusufdupsc1/clientflow-pro/blob/main/routes/web.php) (Routes), [`app/Support/Tenancy/Tenant.php`](https://github.com/yusufdupsc1/clientflow-pro/blob/main/app/Support/Tenancy/Tenant.php) (Tenancy), [`app/Http/Controllers/Web`](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Http/Controllers/Web) (Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["Laravel app"]
  node_node_routes["Routes<br/>HTTP entrypoints<br/>[web.php]"]
  node_node_web["Web UI<br/>Blade controllers"]
  node_node_api["JSON API<br/>API controllers"]
  node_node_public["Public flows<br/>guest controllers"]
  node_node_auth["Auth"]
  node_node_tenancy{{"Tenancy<br/>org scoping<br/>[Tenant.php]"}}
  node_node_models[("Domain models<br/>Eloquent models")]
  node_node_policies["Policies<br/>authorization"]
  node_node_billing["Billing actions<br/>invoice workflow"]
  node_node_stripe{{"Stripe<br/>payment integration<br/>[StripeService.php]"}}
  node_node_async["Async work<br/>jobs and webhooks"]
  node_node_support["Support services<br/>shared logic"]
  node_node_sdk["SDKs<br/>client libraries<br/>[ClientflowApi.php]"]
end

subgraph group_group_ui["Presentation"]
  node_node_views["Blade UI<br/>views"]
  node_node_assets["Frontend assets<br/>build assets<br/>[app.js]"]
end

subgraph group_group_data["Persistence"]
  node_node_db[("Database<br/>migrations")]
  node_node_storage[("Storage<br/>files and artifacts")]
end

subgraph group_group_ops["Operations"]
  node_node_console["Console<br/>artisan commands"]
  node_node_ci["Deployments<br/>ci/cd and runtime"]
  node_node_tests["Tests<br/>feature coverage"]
end

node_node_routes -->|"serves"| node_node_web
node_node_routes -->|"serves"| node_node_api
node_node_routes -->|"serves"| node_node_public
node_node_routes -->|"serves"| node_node_auth
node_node_web -->|"renders"| node_node_views
node_node_api -->|"reads/writes"| node_node_models
node_node_public -->|"initiates"| node_node_stripe
node_node_auth -->|"authenticates"| node_node_models
node_node_tenancy -->|"scopes"| node_node_models
node_node_tenancy -->|"guards"| node_node_web
node_node_policies -->|"authorizes"| node_node_models
node_node_billing -->|"updates"| node_node_models
node_node_billing -->|"uses"| node_node_support
node_node_stripe -->|"hands off"| node_node_async
node_node_async -->|"applies"| node_node_models
node_node_support -->|"stores"| node_node_storage
node_node_views -->|"loads"| node_node_assets
node_node_db -->|"persists"| node_node_models
node_node_console -->|"dispatches"| node_node_async
node_node_ci -->|"builds"| node_node_assets
node_node_tests -->|"covers"| node_node_tenancy
node_node_tests -->|"covers"| node_node_stripe
node_node_sdk -->|"consumes"| node_node_api

click node_node_routes "https://github.com/yusufdupsc1/clientflow-pro/blob/main/routes/web.php"
click node_node_web "https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Http/Controllers/Web"
click node_node_api "https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Http/Controllers/Api"
click node_node_public "https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Http/Controllers/Public"
click node_node_auth "https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Http/Controllers/Auth"
click node_node_tenancy "https://github.com/yusufdupsc1/clientflow-pro/blob/main/app/Support/Tenancy/Tenant.php"
click node_node_models "https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Models"
click node_node_policies "https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Policies"
click node_node_billing "https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Actions/Billing"
click node_node_stripe "https://github.com/yusufdupsc1/clientflow-pro/blob/main/app/Services/StripeService.php"
click node_node_async "https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Jobs"
click node_node_support "https://github.com/yusufdupsc1/clientflow-pro/blob/main/app/Services/InvoicePdfService.php"
click node_node_views "https://github.com/yusufdupsc1/clientflow-pro/tree/main/resources/views"
click node_node_assets "https://github.com/yusufdupsc1/clientflow-pro/blob/main/resources/js/app.js"
click node_node_db "https://github.com/yusufdupsc1/clientflow-pro/tree/main/database/migrations"
click node_node_storage "https://github.com/yusufdupsc1/clientflow-pro/tree/main/storage/app/public"
click node_node_console "https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Console/Commands"
click node_node_ci "https://github.com/yusufdupsc1/clientflow-pro/tree/main/Dockerfile"
click node_node_tests "https://github.com/yusufdupsc1/clientflow-pro/tree/main/tests/Feature"
click node_node_sdk "https://github.com/yusufdupsc1/clientflow-pro/blob/main/sdk/php/ClientflowApi.php"

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_node_routes,node_node_web,node_node_api,node_node_public,node_node_auth,node_node_tenancy,node_node_models,node_node_policies,node_node_billing,node_node_stripe,node_node_async,node_node_support,node_node_sdk toneBlue
class node_node_views,node_node_assets toneAmber
class node_node_db,node_node_storage toneMint
class node_node_console,node_node_ci,node_node_tests toneRose
```

## Components

### Laravel app

Core application code for web, API, jobs, models, and support services.

- [Routes](https://github.com/yusufdupsc1/clientflow-pro/blob/main/routes/web.php): HTTP entrypoints · Route files split auth, web UI, and console commands. · `routes/web.php`
- [Web UI](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Http/Controllers/Web): Blade controllers · Server-rendered dashboard, CRUD, settings, exports, and audit views. · `app/Http/Controllers/Web`
- [JSON API](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Http/Controllers/Api): API controllers · Structured API for clients, invoices, payments, projects, invitations, audit, and tokens. · `app/Http/Controllers/Api`
- [Public flows](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Http/Controllers/Public): guest controllers · Client portal and invoice payment pages for unauthenticated users. · `app/Http/Controllers/Public`
- [Auth](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Http/Controllers/Auth): authentication · Login, registration, password, and email verification flows. · `app/Http/Controllers/Auth`
- [Tenancy](https://github.com/yusufdupsc1/clientflow-pro/blob/main/app/Support/Tenancy/Tenant.php): org scoping · Organization selection and tenant context used to isolate data access. · `app/Support/Tenancy/Tenant.php`
- [Domain models](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Models): Eloquent models · Organizations, clients, projects, invoices, payments, invitations, roles, permissions, logs, files, and webhook records. · `app/Models`
- [Policies](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Policies): authorization · Policy layer enforcing organization access and entity-level permissions. · `app/Policies`
- [Billing actions](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Actions/Billing): invoice workflow · Invoice creation, update, send, payment posting, refund, and void actions. · `app/Actions/Billing`
- [Stripe](https://github.com/yusufdupsc1/clientflow-pro/blob/main/app/Services/StripeService.php): payment integration · Checkout, webhook intake, and Stripe service boundary for invoice payments. · `app/Services/StripeService.php`
- [Async work](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Jobs): jobs and webhooks · Queued exports and asynchronous Stripe webhook processing. · `app/Jobs`
- [Support services](https://github.com/yusufdupsc1/clientflow-pro/blob/main/app/Services/InvoicePdfService.php): shared logic · PDF generation, billing utilities, activity logging, permissions, and webhook dispatch. · `app/Services/InvoicePdfService.php`
- [SDKs](https://github.com/yusufdupsc1/clientflow-pro/blob/main/sdk/php/ClientflowApi.php): client libraries · Packaged PHP and JavaScript API clients. · `sdk/php/ClientflowApi.php`

### Presentation

Blade views, layouts, and frontend assets for the app and public flows.

- [Blade UI](https://github.com/yusufdupsc1/clientflow-pro/tree/main/resources/views): views · Layouts, dashboard, auth, tenant settings, clients, projects, invoices, payments, portal, and reusable components. · `resources/views`
- [Frontend assets](https://github.com/yusufdupsc1/clientflow-pro/blob/main/resources/js/app.js): build assets · CSS and JavaScript built with Vite and Tailwind. · `resources/js/app.js`

### Persistence

Database schema, storage, and generated artifacts.

- [Database](https://github.com/yusufdupsc1/clientflow-pro/tree/main/database/migrations): migrations · Schema for tenants, billing, access control, webhooks, tokens, and logs. · `database/migrations`
- [Storage](https://github.com/yusufdupsc1/clientflow-pro/tree/main/storage/app/public): files and artifacts · Private/public storage for uploads, branding assets, exported files, and generated documents. · `storage/app/public`

### Operations

Console, queues, deployment, and CI/CD around the monolith.

- [Console](https://github.com/yusufdupsc1/clientflow-pro/tree/main/app/Console/Commands): artisan commands · Operational commands for demo seeding, overdue processing, reminders, currency repair, and mail testing. · `app/Console/Commands`
- [Deployments](https://github.com/yusufdupsc1/clientflow-pro/tree/main/Dockerfile): ci/cd and runtime · Docker, Nginx, Render config, and GitHub workflows for build and deployment. · `Dockerfile`
- [Tests](https://github.com/yusufdupsc1/clientflow-pro/tree/main/tests/Feature): feature coverage · Feature-heavy tests focused on tenancy, auth, billing, Stripe, API, tokens, and webhooks. · `tests/Feature`

## Connections

- Routes → Web UI: serves · Web routes dispatch to dashboard and CRUD controllers.
- Routes → JSON API: serves · API routes expose JSON endpoints.
- Routes → Public flows: serves · Public routes expose portal and payment pages.
- Routes → Auth: serves · Auth routes handle login and account flows.
- Web UI → Blade UI: renders · Web controllers return Blade views.
- JSON API → Domain models: reads/writes · API controllers operate on domain models.
- Public flows → Stripe: initiates · Guest payment flows start Stripe checkout.
- Auth → Domain models: authenticates · User registration and sessions depend on user records.
- Tenancy → Domain models: scopes · Organization context constrains model access.
- Tenancy → Web UI: guards · Middleware redirects or blocks when no organization is selected.
- Policies → Domain models: authorizes · Entity policies gate access to tenant-owned records.
- Billing actions → Domain models: updates · Billing actions create and transition invoices and payments.
- Billing actions → Support services: uses · Billing workflows rely on PDF and shared billing helpers.
- Stripe → Async work: hands off · Webhook controller queues Stripe event processing.
- Async work → Domain models: applies · Jobs reconcile invoice, payment, and webhook state.
- Support services → Storage: stores · PDFs, files, and exports land in storage.
- Blade UI → Frontend assets: loads · Blade UI is styled and enhanced by built assets.
- Database → Domain models: persists · Models are backed by the relational schema.
- Console → Async work: dispatches · Commands trigger background or deferred workflows.
- Deployments → Frontend assets: builds · Deployment pipeline builds frontend assets and runtime images.
- Tests → Tenancy: covers · Tests verify organization isolation behavior.
- Tests → Stripe: covers · Tests verify payment and webhook integration.
- SDKs → JSON API: consumes · Generated SDKs target the public API surface.