Architecture Documentation

Generated: 2025-11-16

Executive Summary

Flowcode is a full-stack enterprise SaaS application built on Laravel 12 with a Vue 3 frontend. It implements a multi-tenant architecture for organizational management, featuring business catalogues, compliance tracking, project management (OPTT), and session scheduling. The application serves as a comprehensive business development and compliance platform.

Technology Stack

Layer	Technology	Version	Purpose
Backend Framework	Laravel	12.x	Core PHP framework
Language	PHP	8.3.27	Server-side logic
Frontend Framework	Vue.js	3.5	Reactive UI components
SPA Bridge	Inertia.js	2.x	Server-side routing, SPA UX
Admin Panel	Filament	3.x	Multi-panel CRUD admin
State Management	Pinia	3.x	Client-side state
CSS Framework	Tailwind CSS	3.x	Utility-first styling
Component Library	PrimeVue	4.x	Enterprise UI components
Build Tool	Vite	6.x	Asset bundling
Database	MySQL	8.0+	Primary data store
Cache/Queue	Redis	7.x	Session, cache, queues
Testing	Pest + PHPUnit	4.x / 12.x	Automated testing
Queue Dashboard	Laravel Horizon	5.x	Job monitoring
Monitoring	Laravel Pulse	1.x	Performance monitoring
Multi-tenancy	Spatie	4.x	Tenant isolation
API Auth	Laravel Sanctum	4.x	Token authentication

Architecture Pattern

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│                    Client Browser                       │
│  ┌───────────────┐  ┌─────────────┐  ┌──────────────┐ │
│  │   Vue 3 SPA   │  │  Inertia.js │  │   Tailwind   │ │
│  │  Components   │  │    Client   │  │      CSS     │ │
│  └───────────────┘  └─────────────┘  └──────────────┘ │
└────────────────────────┬────────────────────────────────┘
                         │ HTTPS
                         ▼
┌─────────────────────────────────────────────────────────┐
│                    Laravel Backend                       │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │   Routes    │  │  Controllers │  │   Middleware  │ │
│  │  (Inertia)  │  │   (98 files) │  │  (Auth/RBAC)  │ │
│  └─────────────┘  └──────────────┘  └───────────────┘ │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │   Models    │  │   Services   │  │    Policies   │ │
│  │ (176 files) │  │   (Actions)  │  │ (Authorization)│ │
│  └─────────────┘  └──────────────┘  └───────────────┘ │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │  Filament   │  │    Events    │  │     Jobs      │ │
│  │   (3 Panels)│  │  & Listeners │  │   (26 async)  │ │
│  └─────────────┘  └──────────────┘  └───────────────┘ │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                    Data Layer                           │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │    MySQL    │  │    Redis     │  │      S3       │ │
│  │  (Primary)  │  │ (Cache/Queue)│  │  (File Store) │ │
│  └─────────────┘  └──────────────┘  └───────────────┘ │
└─────────────────────────────────────────────────────────┘

Core Architectural Components

1. Multi-Tenancy Architecture

Spatie Multi-Tenancy
        │
        ▼
    Tenant (Domain)
        │
        ▼
    Organisation
    ┌───┴───┐
    │       │
   Users   Data
   RBAC    Isolation

Tenant Identification: Domain/subdomain-based
Data Isolation: Organization-scoped queries
Session Isolation: Per-tenant sessions
Configuration: config/multitenancy.php

2. Authentication Layer

Multiple authentication strategies:

Auth Request
      │
      ▼
AuthController
      │
      ├─► PasswordAuth (traditional)
      ├─► PasswordlessEmailAuth (magic link)
      ├─► SocialGoogleAuth (OAuth)
      └─► Firebase Auth (external service)

Sanctum for SPA token auth
Policy-based authorization
Permission-based access control
Role hierarchy per organization

3. Inertia.js SPA Architecture

Browser Request
      │
      ▼
Laravel Route
      │
      ▼
Inertia::render('Page', $props)
      │
      ▼
Vue 3 Page Component
      │
      ├─► Props from server
      ├─► Client-side state (Pinia)
      └─► Server-side navigation

Benefits: - SEO-friendly (server-rendered initial load) - No API maintenance overhead - Type-safe data transfer - Laravel session/CSRF protection

4. Filament Multi-Panel Architecture

/admin-panel           → Super Admin Panel
/creator-panel         → Content Creator Panel
/org-panel             → Organisation Panel

Each panel contains: - Resources (CRUD interfaces) - Pages (custom workflows) - Widgets (dashboard components) - Custom components (forms, tables)

Domain Model Architecture

Core Domain Aggregates

1. Organisation Aggregate (Root)

Organisation (Tenant Root)
├── OrganisationUser (Members)
├── OrganisationRole (Custom Roles)
├── OrganisationPermission (Access Control)
├── Division → Department (Structure)
├── OrganisationCatalogue (Assigned Catalogues)
└── OPTT Entities (Business Planning)

2. Catalogue Aggregate

Catalogue (Business Knowledge)
├── CatalogueModule (Sections)
│   └── Element (Content Units)
│       ├── ElementTab (primer, strategy, custom, uploads, optts)
│       │   └── Field (Data Fields)
│       │       └── FieldProgress (User Progress)
│       ├── ElementNotice (Notifications)
│       ├── ElementUpload (Attachments)
│       └── Graphic (Visual Assets)
└── CatalogueProgress (User Completion)

3. OPTT Aggregate (Business Planning)

Objective (Strategic Goals)
└── Project (Implementation)
    └── Task (Action Items)
        └── Target (KPIs)

LinkedOptt (Cross-references)
OpttAttachment (Supporting Documents)
Comment (Discussions)

4. Compliance Aggregate

IndicatorCompliance (Requirements)
├── IndicatorTask (Assignments)
│   └── IndicatorSubmission (Evidence)
│       └── IndicatorSubmissionReview (Verification)
└── IndicatorReviewTask (Review Workflow)

Request/Response Flow

Web Request Flow

1. HTTP Request
   └─► public/index.php

2. Laravel Bootstrap
   └─► bootstrap/app.php

3. HTTP Kernel
   └─► app/Http/Kernel.php (middleware stack)

4. Routing
   └─► routes/web.php
       ├─► Auth middleware
       ├─► Tenant middleware
       └─► Policy middleware

5. Controller
   └─► app/Http/Controllers/
       └─► Business logic
       └─► Data fetching

6. Inertia Response
   └─► Inertia::render('Page', $data)

7. Vue Component
   └─► resources/ts/Pages/
       └─► Reactive UI

API Request Flow

1. API Request
   └─► routes/api.php

2. Sanctum Authentication
   └─► auth:sanctum middleware

3. Policy Authorization
   └─► policy:view,Model middleware

4. API Controller
   └─► app/Http/Controllers/Api/

5. JSON Response
   └─► Spatie Data DTOs

Data Flow Patterns

Progress Tracking

User interacts with Field
        │
        ▼
FieldProgressController
        │
        ▼
FieldProgress (stored)
        │
        ├─► Calculate ElementProgress
        │
        └─► Update CatalogueProgress

Event-Driven Architecture

Model Event (created/updated)
        │
        ▼
Observer (App\Observers\)
        │
        ▼
Event Dispatch
        │
        ├─► Listener (sync)
        │
        └─► Queued Job (async)
                │
                ▼
           Horizon Worker

Notification System

Business Event
        │
        ▼
Notification Class
        │
        ├─► Mail Channel
        ├─► Database Channel (in-app)
        └─► Slack Channel

Security Architecture

Authentication Security

CSRF protection (Laravel default)
Session encryption
Password hashing (bcrypt)
Rate limiting (throttle middleware)
2FA support (Firebase)

Authorization Security

Policy-based authorization
Role-based access control (RBAC)
Permission granularity (UserPermissions enum)
Tenant isolation (data scoping)
Organization-level permissions

Data Security

Input validation (Form Requests)
XSS protection (DOMPurify in Vue)
SQL injection prevention (Eloquent ORM)
File upload validation
Encrypted sensitive data

Scalability Architecture

Horizontal Scaling

Load Balancer
      │
      ├─► App Server 1 (Laravel)
      ├─► App Server 2 (Laravel)
      └─► App Server N (Laravel)
            │
            ▼
      Shared Services
      ├─► MySQL (Primary/Replica)
      ├─► Redis Cluster
      └─► S3 (File Storage)

Queue Architecture

HTTP Request
      │
      ▼
Dispatch Job
      │
      ▼
Redis Queue
      │
      ▼
Horizon Worker Pool
      │
      ├─► Default Queue
      ├─► Notifications Queue
      └─► Exports Queue

Caching Strategy

Configuration Cache: php artisan config:cache
Route Cache: php artisan route:cache
View Cache: Compiled Blade templates
Query Cache: Redis-backed model caching
Session Cache: Redis sessions

Monitoring Architecture

Production Monitoring

Application
      │
      ├─► Laravel Pulse (Performance)
      │   ├─► Slow queries
      │   ├─► Memory usage
      │   └─► Queue health
      │
      ├─► Laravel Nightwatch (Errors)
      │   ├─► Exception tracking
      │   ├─► Error aggregation
      │   └─► Alerting
      │
      └─► Spatie Health (System)
          ├─► Database connectivity
          ├─► Redis connectivity
          └─► Disk space

Development Monitoring

Telescope: Request/query profiling
Debugbar: Real-time profiling
Activity Log: User action tracking

Integration Points

External Services

Firebase - Authentication service
AWS S3 - File storage
OpenAI - AI features (prompts, analysis)
Mandrill - Transactional email
Slack - Notifications
Kraken.io - Image optimization

Internal Integration

Filament ↔ Eloquent Models
Vue Components ↔ Inertia Props
Jobs ↔ Horizon Dashboard
Events ↔ Listeners

Deployment Architecture

CI/CD Pipeline

Git Push (develop)
      │
      ▼
GitHub Actions
      │
      ├─► Laravel Tests (.github/workflows/laravel.yml)
      │   ├─► PHPUnit
      │   ├─► Pest
      │   └─► Pint (formatting)
      │
      └─► Dusk Tests (.github/workflows/dusk.yml)
          └─► Browser E2E tests

      │
      ▼
Staging Deployment
      │
      ▼
Production Deployment

Environment Promotion

Local (Valet/Homestead)
      │
      ▼
Staging (Pre-production)
      │
      ▼
Production (Live)

Design Patterns Used

Repository Pattern - Data access abstraction
Service Layer - Business logic encapsulation
Action Classes - Single-purpose operations
Observer Pattern - Model lifecycle hooks
Strategy Pattern - Authentication strategies
Facade Pattern - Service access
Factory Pattern - Model creation (testing)
Decorator Pattern - Filament components
Command Pattern - Artisan commands
Event Sourcing - Activity logging

Codebase Metrics

Metric	Count	Notes
Eloquent Models	176	Core domain entities
Vue Components	719	UI building blocks
Controllers	98	Request handlers
Database Migrations	396	Schema evolution
Queue Jobs	26	Async processing
Test Files	235	Automated tests
Service Providers	9	Boot configuration
Filament Panels	3	Admin interfaces

Future Architecture Considerations

Microservices: Consider extracting compliance/indicators into separate service
GraphQL: Potential API layer for complex queries
Event Store: Full event sourcing for audit requirements
CDN Integration: Static asset delivery optimization
Real-time Features: WebSocket integration for live updates