Krow-workspace/internal/launchpad/assets/documents/legacy/web-application/architecture.md

Application Overview: KROW Web Platform (Backend)

1. Executive Summary

The KROW Web Platform is the central "brain" and "command center" of the entire KROW ecosystem. While the mobile apps are the tools used in the field, this web application is the engine that powers them.

It serves two primary functions:

1. The Engine: It processes all data from the mobile apps—saving new events, finding available staff, handling payments, and verifying check-ins.
2. The Control Tower (Admin Panel): It provides a powerful website where KROW administrators can oversee the entire business, manage users, resolve disputes, and configure system-wide settings.

2. High-Level Architecture

The application follows a Monolithic Web Architecture using the Laravel framework. This is a battle-tested, robust structure ideal for building complex, data-heavy business platforms.

• The API Server (The Voice): It listens for requests from the mobile apps (using GraphQL). When a phone asks "Show me my shifts," this server understands the question, fetches the answer, and sends it back.
• The Database (The Memory): A centralized vault where all information (User profiles, Shift details, Invoices) is safely stored.
• The Admin Interface (The Dashboard): A secure website (built with Laravel Nova) that allows internal staff to view and edit this data directly without writing code.

3. Major Components & Modules

The system is divided into logical "domains" representing different parts of the business.

A. Core Business Logic (app/Models, app/Actions)

• Purpose: The rules of the business.
• Key Functions: Defining what an "Event" is, how a "Shift" relates to a "Position," and ensuring that a Staff member cannot be in two places at once.

B. API Layer (app/GraphQL)

• Purpose: The communication hub for mobile apps.
• Key Functions:
  • Client API: specialized endpoints for business owners to create jobs.
  • Staff API: specialized endpoints for workers to find jobs.
  • Authentication: Verifying who is asking for data.

C. Administration Panel (app/Nova)

• Purpose: Internal management tool.
• Key Functions:
  • User Management: Approving new staff, verifying documents.
  • Content Management: Managing skills lists, certificate types, and system tags.
  • Audit Logs: Viewing history of who did what.

D. Financial Engine (app/Models/Payroll, app/Models/Invoice)

• Purpose: Money management.
• Key Functions: Calculating staff pay based on hours worked, generating invoices for clients, and tracking payment status.

E. Notification System (app/Notifications)

• Purpose: Keeping everyone in the loop.
• Key Functions: Sending emails, SMS, or push notifications when shifts are accepted, cancelled, or when payments are processed.

4. Component Responsibilities

• Controllers/Resolvers: These receive a request (e.g., "Create Shift"), validate it (e.g., "Is the date in the future?"), and pass it to the Logic layer.
• Service Classes: These perform specific complex tasks, like "Calculate total cost for this event including tax and service fees."
• Eloquent Models: These represent the data tables. The Staff model knows how to talk to the staff table in the database.
• Nova Resources: These define how data looks in the Admin Panel. A StaffResource defines that a staff member has a name, photo, and rating, and tells the admin panel how to display them.

5. External System Communication

• Firebase: Uses Firebase Authentication for secure user identity and Firebase Cloud Messaging for push notifications.
• Database (MySQL/PostgreSQL): The primary storage for all application data.
• Storage (AWS S3 / DO Spaces): Stores user uploaded files like profile photos and certificates.
• Payment Gateway (Stripe/Similar): (Implied) Handles the actual processing of credit card transactions and payouts.
• Maps/Geolocation APIs: Used to validate addresses and calculate distances between staff and venues.

6. Architectural Patterns

• MVC (Model-View-Controller): The traditional Laravel pattern, adapted here where "View" is mostly replaced by the GraphQL API or the Nova Admin panel.
• Action-Based Domain Logic: Complex business operations (like "Assign Staff to Shift") are often encapsulated in single "Action" classes rather than hidden inside massive models.
• GraphQL Schema-First: The API is defined by a typed schema (.graphql files), ensuring a strict contract between the frontend and backend.

7. Key Design Decisions & Impact

A. GraphQL (Lighthouse)

• Decision: Using GraphQL instead of traditional REST API endpoints.
• Why it matters: Allows the mobile apps to be very efficient. They can ask for deep, related data (Event -> Shifts -> Staff -> Ratings) in a single network request, making the apps faster.

B. Laravel Nova

• Decision: Using a pre-built administration package instead of building a custom admin panel from scratch.
• Why it matters: Drastically reduced development time. It provides a professional, secure, and feature-rich dashboard out of the box, allowing the team to focus on the unique app features.

C. Role-Based Access Control (Spatie Permissions)

• Decision: Implementing a granular permission system.
• Why it matters: Security. It ensures that a "Client" can never see "Admin" data, and a "Staff" member can only see shifts relevant to them.

8. Overview Diagram

flowchart TD
    %% Define Styles
    classDef interface fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef logic fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#bf360c
    classDef data fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    classDef external fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c

    subgraph Server_Application [KROW Web Platform]
        direction TB

        subgraph Interfaces [Access Layers]
            direction TB
            Admin_Panel[Admin Panel (Laravel Nova)]:::interface
            GraphQL_API[GraphQL API (Lighthouse)]:::interface
        end

        subgraph Domain_Logic [Core Business Engine]
            direction TB
            Models[Data Models]:::logic
            Actions[Business Actions & Rules]:::logic
            Notifications[Notification System]:::logic
            Payroll[Payroll & Invoicing Engine]:::logic
        end

        subgraph Data_Storage [Persistence Layer]
            direction TB
            MySQL[(Main Database)]:::data
            Storage[File Storage (S3/DO Spaces)]:::data
        end
    end

    subgraph External_World [External Ecosystem]
        direction TB
        Mobile_Apps[Mobile Apps (Client & Staff)]:::external
        Firebase[Firebase (Auth & Push)]:::external
        Maps_API[Maps & Geolocation]:::external
    end

    %% Connections
    Mobile_Apps <-->|GraphQL Requests| GraphQL_API
    
    Admin_Panel --> Actions
    GraphQL_API --> Actions
    
    Actions --> Models
    Actions --> Payroll
    Actions --> Notifications
    
    Models <--> MySQL
    Models <--> Storage
    
    Notifications -->|Send Push/Email| Firebase
    Actions -->|Validate Location| Maps_API