How yusufdupsc1/clientflow-pro works
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: Models Domain models · web.php Routes · Tenant.php Tenancy · Web Web UI
Components 20
Laravel app
Core application code for web, API, jobs, models, and support services.
- Routes · Route files split auth, web UI, and console commands.
routes/web.php - Web UI · Server-rendered dashboard, CRUD, settings, exports, and audit views.
app/Http/Controllers/Web - JSON API · Structured API for clients, invoices, payments, projects, invitations, audit, and tokens.
app/Http/Controllers/Api - Public flows · Client portal and invoice payment pages for unauthenticated users.
app/Http/Controllers/Public - Auth · Login, registration, password, and email verification flows.
app/Http/Controllers/Auth - Tenancy · Organization selection and tenant context used to isolate data access.
app/Support/Tenancy/Tenant.php - Domain models · Organizations, clients, projects, invoices, payments, invitations, roles, permissions, logs, files, and webhook records.
app/Models - Policies · Policy layer enforcing organization access and entity-level permissions.
app/Policies - Billing actions · Invoice creation, update, send, payment posting, refund, and void actions.
app/Actions/Billing - Stripe · Checkout, webhook intake, and Stripe service boundary for invoice payments.
app/Services/StripeService.php - Async work · Queued exports and asynchronous Stripe webhook processing.
app/Jobs - Support services · PDF generation, billing utilities, activity logging, permissions, and webhook dispatch.
app/Services/InvoicePdfService.php - SDKs · 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 · Layouts, dashboard, auth, tenant settings, clients, projects, invoices, payments, portal, and reusable components.
resources/views - Frontend assets · CSS and JavaScript built with Vite and Tailwind.
resources/js/app.js
Persistence
Database schema, storage, and generated artifacts.
Operations
Console, queues, deployment, and CI/CD around the monolith.
- Console · Operational commands for demo seeding, overdue processing, reminders, currency repair, and mail testing.
app/Console/Commands - Deployments · Docker, Nginx, Render config, and GitHub workflows for build and deployment.
Dockerfile - Tests · Feature-heavy tests focused on tenancy, auth, billing, Stripe, API, tokens, and webhooks.
tests/Feature
Connections 23
- 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.