# orchidsoftware/platform architecture

> Architecture diagram of the GitHub repository orchidsoftware/platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/orchidsoftware/platform
- Repository: https://github.com/orchidsoftware/platform

## Overview

##### Project Type & Purpose
- This is a Laravel package (“orchid/platform”), not a standalone application.
- Purpose: provide a code-driven back-office framework (admin panels, dashboards) for Laravel, with form builders, filtering, notifications, SPA-like UX via Hotwire/Turbo, and scaffolding commands.

##### High-Level Components
A. Front-end (Client Layer)
- public/assets/app.js + Stimulus controllers (resources/js/controllers)
- public/assets/app.css (Sass compiled from resources/sass)
- Turbo frames/streams for partial updates (Hotwire)
B. Application (Server Layer)
- Laravel HTTP Kernel & Middleware (config/platform.php, src/Platform/Http/Middleware)
- Routes (routes/auth.php, routes/dashboard.php + stubbed routes)
- Controllers (src/Platform/Http/Controllers + AsyncController, AttachmentController, IndexController, etc.)
- “Screens” abstraction (src/Screen & src/Platform/Http/Screens)—encapsulates page logic, actions, layouts
- Blade Views & Layouts (resources/views + platform-provided partials)
- ServiceProvider (OrchidServiceProvider) which binds facades, publishes assets, registers commands, events, routes
- Artisan Commands (src/Platform/Commands)—generator commands for screens, fields, filters, layouts, stubs
- Core Modules:
– Attachment (src/Attachment: engines, models, contracts)
– Alert/Toast (src/Alert)
– Access Control (src/Access: roles, permissions, impersonation)
– Filters & Sorting (src/Filters)
– Metrics (src/Metrics)
– Support & Facades (src/Support)
C. Persistence (Data Layer)
- Database migrations & seeders (database/migrations, database/seeders)
- Eloquent Models (src/Platform/Models + Attachment models)
- Laravel Scout / Search integration (optional)
- File storage for attachments (config/platform.php + Events & Listeners)
D. CLI & Events
- Artisan CLI commands (scaffolding/stubs in stubs/)
- Event system (src/Platform/Events) for InstallEvent, UploadFileEvent, etc.

##### Relationships & Data Flow
1. Browser → HTTP Request → Laravel Kernel
2. Kernel → Middleware (Access, Turbo, BladeIcons) → Route resolution
3. Route → Platform/Screen Controller → Screen class
4. Screen → Queries/Repositories → Eloquent Models → Database
5. Screen → Build Layout → Render Blade View → Turbo frame/HTML response
6. Client (Stimulus) intercepts links/forms → issues Turbo requests → async controllers → JSON/HTML fragments → updates DOM
7. Actions (filters, attach/upload) → AttachmentController → Storage → Events → Notifications
8. Artisan (CLI) → OrchidServiceProvider → Command classes → generate stubs → publish package resources

##### Architectural Patterns & Design Principles
- MVC + “Screen” abstraction over Controllers & Views
- Service Provider / Service Container for binding facades & commands
- Command Pattern for scaffolding & publishing resources
- Event-Driven design for file uploads, role changes, installation hooks
- Eloquent ORM for data access; Repositories for Queries
- Stimulus + Hotwire/Turbo for SPA-like UX

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layers Definition
    subgraph "Client Layer" 
        direction TB
        Browser["Browser"]:::client
        Stimulus["Stimulus Controllers"]:::client
        Turbo["Turbo Frames/Streams"]:::client
        AppJS["app.js"]:::client
        AppCSS["app.css"]:::client
    end

    subgraph "Application Layer"
        direction TB
        Kernel["Laravel HTTP Kernel"]:::app
        Middleware["Middleware"]:::app
        Routes["Route Definitions"]:::app
        Controllers["HTTP Controllers"]:::app
        Screens["Screens Abstraction"]:::app
        Views["Blade Views & Layouts"]:::app
        ServiceProvider["OrchidServiceProvider"]:::app
        subgraph "Core Modules"
            direction TB
            Attachment["Attachment Module"]:::module
            Alert["Alert & Toast Module"]:::module
            Access["Access Control Module"]:::module
            Filters["Filters & Sorting Module"]:::module
            Metrics["Metrics Module"]:::module
            Support["Support & Facades"]:::module
        end
    end

    subgraph "Persistence Layer"
        direction TB
        Migrations["Database Migrations"]:::data
        Seeders["Database Seeders"]:::data
        Models["Eloquent Models"]:::data
        Storage["File Storage"]:::data
        Database["Database"]:::data
    end

    subgraph "CLI & Events Layer"
        direction TB
        CLI["Artisan CLI"]:::cli
        Commands["Artisan Commands"]:::cli
        Stubs["Stub Templates"]:::cli
        Events["Event System"]:::cli
    end

    %% Connections
    Browser -->|"intercepts links/forms"| Stimulus
    Stimulus -->|"issues Turbo request"| Turbo
    Turbo -->|"HTTP request"| Kernel
    Kernel -->|"passes through"| Middleware
    Middleware -->|"resolves to"| Routes
    Routes -->|"calls"| Controllers
    Controllers -->|"invokes"| Screens
    Screens -->|"queries"| Models
    Models -->|"DB query"| Database
    Database -->|"returns data"| Models
    Screens -->|"builds layout"| Views
    Views -->|"renders HTML"| Turbo
    Turbo -->|"updates DOM"| Browser

    Controllers -->|"attachment actions"| Attachment
    Attachment -->|"stores files"| Storage
    Storage -->|"dispatch"| Events
    Events -->|"notify"| Alert

    ServiceProvider -->|"registers"| Middleware
    ServiceProvider -->|"registers"| Routes
    ServiceProvider -->|"registers"| Controllers
    ServiceProvider -->|"registers"| Commands
    ServiceProvider -->|"binds facades"| Support

    CLI -->|"executes"| Commands
    Commands -->|"generate"| Stubs
    Stubs -->|"publish resources"| Views

    %% Click Events
    click AppJS "https://github.com/orchidsoftware/platform/blob/master/public/assets/app.js"
    click AppCSS "https://github.com/orchidsoftware/platform/blob/master/public/assets/app.css"
    click Stimulus "https://github.com/orchidsoftware/platform/tree/master/resources/js/controllers/"
    click Kernel "https://github.com/orchidsoftware/platform/blob/master/config/platform.php"
    click Middleware "https://github.com/orchidsoftware/platform/tree/master/src/Platform/Http/Middleware/"
    click Routes "https://github.com/orchidsoftware/platform/blob/master/routes/auth.php"
    click Routes "https://github.com/orchidsoftware/platform/blob/master/routes/dashboard.php"
    click Controllers "https://github.com/orchidsoftware/platform/tree/master/src/Platform/Http/Controllers/"
    click Screens "https://github.com/orchidsoftware/platform/tree/master/src/Screen/"
    click Screens "https://github.com/orchidsoftware/platform/tree/master/src/Platform/Http/Screens/"
    click Views "https://github.com/orchidsoftware/platform/tree/master/resources/views/"
    click Views "https://github.com/orchidsoftware/platform/tree/master/resources/views/layouts/"
    click ServiceProvider "https://github.com/orchidsoftware/platform/blob/master/src/Platform/OrchidServiceProvider.php"
    click Commands "https://github.com/orchidsoftware/platform/tree/master/src/Platform/Commands/"
    click Attachment "https://github.com/orchidsoftware/platform/tree/master/src/Attachment/"
    click Alert "https://github.com/orchidsoftware/platform/tree/master/src/Alert/"
    click Access "https://github.com/orchidsoftware/platform/tree/master/src/Access/"
    click Filters "https://github.com/orchidsoftware/platform/tree/master/src/Filters/"
    click Metrics "https://github.com/orchidsoftware/platform/tree/master/src/Metrics/"
    click Support "https://github.com/orchidsoftware/platform/tree/master/src/Support/"
    click Migrations "https://github.com/orchidsoftware/platform/tree/master/database/migrations/"
    click Seeders "https://github.com/orchidsoftware/platform/tree/master/database/seeders/"
    click Models "https://github.com/orchidsoftware/platform/tree/master/src/Platform/Models/"
    click Models "https://github.com/orchidsoftware/platform/tree/master/src/Attachment/Models/"
    click Events "https://github.com/orchidsoftware/platform/tree/master/src/Platform/Events/"
    click Stubs "https://github.com/orchidsoftware/platform/tree/master/stubs/"

    %% Styles
    classDef client fill:#e0f7fa,stroke:#006064,color:#000
    classDef app fill:#bbdefb,stroke:#0d47a1,color:#000
    classDef module fill:#c8e6c9,stroke:#1b5e20,color:#000
    classDef data fill:#fff9c4,stroke:#f57f17,color:#000
    classDef cli fill:#eceff1,stroke:#37474f,color:#000
```
