System Components

Purpose and Scope

This document catalogs the major system components of the Light framework and their structural relationships. It provides a component-level view of the architecture, identifying key classes, their responsibilities, and how they fit together. For detailed information about specific subsystems:

• Request processing flow: see Request Lifecycle
• Dependency injection mechanics: see Dependency Injection
• Core App class implementation: see Core Application
• GraphQL API details: see GraphQL API
• Security systems: see Authentication and Authorization
• Data layer implementation: see Data Layer

---

Component Architecture Overview

The Light framework is organized into six primary component layers, each encapsulating distinct system responsibilities. The following diagram maps these layers to their concrete implementations in the codebase.

System Layer Mapping

Sources: src/App.php1-941 src/Type/App.php1-544 src/Auth/Service.php1-141 src/Model/User.php1-390

---

Core Application Kernel

The Light\App class serves as the central orchestrator with an importance score of 149.50, making it the most critical component in the system. It implements both MiddlewareInterface and RequestHandlerInterface for PSR-15 compatibility.

Responsibilities

Responsibility	Implementation	Lines
Container initialization	League\Container instantiation	src/App.php68
GraphQL schema factory setup	SchemaFactory configuration	src/App.php121-126
RBAC system loading	Role/permission hierarchy construction	src/App.php306-366
Filesystem mounting	MountManager configuration	src/App.php134-146
Request processing	Middleware pipeline execution	src/App.php500-537
Authentication service injection	Auth\Service instantiation	src/App.php526-534

Component Registration

The constructor registers all core controllers and services into the dependency injection container:

Sources: src/App.php59-147

---

GraphQL API Layer

The GraphQL layer uses GraphQLite for annotation-based schema generation. The system exposes two primary entry points: Light\Type\App (importance: 75.46) for queries and various controller classes for mutations.

GraphQL Entry Points

Schema Factory Configuration

The schema factory is configured in the App constructor with namespace scanning and custom type mappers:

Configuration	Purpose	Location
addNamespace("Light")	Scan Light namespace for types	src/App.php125
addTypeMapperFactory()	Bridge Light\Db models to GraphQL	src/App.php126
setAuthenticationService()	Inject auth service for @Logged	src/App.php529
setAuthorizationService()	Inject auth service for @Right	src/App.php530

Sources: src/App.php121-126 src/Type/App.php1-544

---

Authentication & Authorization Components

The security layer implements a multi-component architecture combining stateless JWT authentication with stateful RBAC authorization.

Security Component Interaction

Component Responsibilities

Auth\Service (src/Auth/Service.php):

• JWT token extraction from cookies or Authorization header lines 38-43
• Token validation and expiration checking lines 50-80
• User context injection into GraphQL resolvers lines 107-113
• Permission checking via isAllowed() lines 122-139
• Session revocation detection via cache line 58

Light\Rbac (loaded in src/App.php):

• Role hierarchy construction lines 308-323
• Permission-to-role mapping from YAML lines 338-343
• Database-stored permission loading lines 345-355
• User-role association lines 358-363
• Wildcard permission support for administrators line 309

Light\Model\User (src/Model/User.php):

• User identity and profile data lines 19-26
• Role membership querying lines 297-311
• Permission checking lines 283-291
• Session management lines 50-82
• 2FA secret storage lines 162-165
• WebAuthn credential storage lines 151-158

Sources: src/Auth/Service.php1-141 src/App.php306-366 src/Model/User.php1-390

---

Data Persistence Layer

The data layer provides ORM functionality with automatic audit trails and revision tracking.

Data Layer Component Stack

Core Model Functionality

Feature	Implementation	Purpose
Automatic timestamps	save() hook	Sets created_time, updated_time
User tracking	save() hook	Sets created_by, updated_by from DI container
Audit logging	delete() hook	Records deletion to EventLog
Revision tracking	EventLog integration	Stores source/target state snapshots
Query filtering	Query::filters()	Declarative filter syntax
Query sorting	Query::sort()	String-based sort specification

Database Access Pattern:

The App class provides database access via getDatabase() line 223 which calls Light\Db\Adapter::Create() to instantiate a connection based on environment variables (DATABASE_*).

Sources: src/App.php223-226 src/Model/User.php48

---

File Storage System

The file storage system uses Flysystem to provide cloud-agnostic file operations across multiple backends.

Storage Architecture

Filesystem Configuration Loading

The App::getFSConfig() method lines 695-714 loads filesystem configurations from the database:

1. Queries Config model for key "fs" line 697
2. Parses JSON array of filesystem definitions line 701
3. Provides default local filesystem if none configured lines 704-712

Each filesystem definition contains:

• name: Mount identifier (e.g., "local", "s3")
• type: Backend type ("local", "s3", "aliyun-oss", "hostlink")
• data: Backend-specific configuration (credentials, endpoints)

MountManager Setup

The constructor initializes the MountManager lines 134-146:

This enables location-based routing: "s3://path/to/file" routes to the S3 adapter, "local://path" routes to local storage.

Sources: src/App.php134-146 src/App.php695-787

---

Configuration & Infrastructure

Configuration is sourced from multiple locations, each serving different lifecycle stages.

Configuration Sources

Configuration Access Patterns

Environment Variables (.env file):

• Accessed via $_ENV superglobal
• Database credentials: DATABASE_HOST, DATABASE_USERNAME, etc.
• JWT secret: $_ENV["JWT_SECRET"] src/App.php647
• Cookie settings: $_ENV["COOKIE_DOMAIN"], $_ENV["COOKIE_SECURE"], etc. lines 616-627

Database Configuration (Config model):

• Static accessor: Config::Value($key, $default) src/App.php107
• Dynamic updates via GraphQL mutations
• Examples: mode, access_token_expire, two_factor_authentication

YAML Files:

• permissions.yml: Parsed at line 338, maps roles to permissions
• menus.yml: Parsed at line 176, defines navigation structure
• Version controlled, deployed with code

Sources: src/App.php107-119 src/App.php233-285 src/App.php338 src/App.php176 src/Type/App.php199-261

---

Component Dependency Graph

This diagram shows the concrete dependency relationships between major components, using actual class names and method calls from the codebase.

Key Dependency Patterns

1. Central Hub Pattern: App aggregates all major subsystems and provides them to other components
2. Factory Pattern: getDrive(), getFS(), getMailer() methods create configured instances on demand
3. Service Locator: Container stores singletons, accessed by type hint in constructors
4. Decorator Pattern: Auth\Service wraps authentication state, injected into GraphQL context
5. Strategy Pattern: Multiple filesystem adapters implement common interface, selected by configuration

Sources: src/App.php59-147 src/App.php500-537 src/Auth/Service.php28-80

---

Summary Table: Component Catalog

Component	Location	Importance	Primary Responsibility
Light\App	src/App.php	149.50	Application kernel, request orchestration
Light\Type\App	src/Type/App.php	75.46	GraphQL root query type
Light\Model\User	src/Model/User.php	52.61	User identity and permissions
Light\Rbac	Loaded in src/App.php128	49.97	Role-based access control
Light\Model	Base class	49.55	ORM base with audit hooks
Light\Db\Adapter	src/App.php225	N/A	Database connection factory
Auth\Service	src/Auth/Service.php	26.88	JWT validation and user context
Controller\FileSystemController	Registered src/App.php93	40.67	File operation mutations
Controller\AuthController	Registered src/App.php77	69.18	Authentication mutations
SchemaFactory	src/App.php124	N/A	GraphQL schema generation
MountManager	src/App.php144	N/A	Multi-backend filesystem routing
Light\Model\Config	Database table	30.74	Runtime configuration storage

Sources: src/App.php1-941 src/Type/App.php1-544 src/Auth/Service.php1-141 src/Model/User.php1-390