Back to Learning Hub

GEMVC Architecture

25 minutes BEGINNER

Understand the complete architecture of GEMVC framework. Learn about directory structure, request flow, components, and how everything works together.

What You'll Learn

Directory Structure

Framework organization and component layout

Request Flow

How requests flow through the system

Component Breakdown

Understanding each layer and component

Video Coming Soon...

Directory Structure

GEMVC follows a clean, organized directory structure that separates concerns and makes the framework easy to understand and maintain. 

src/
├── CLI/              # Command-line interface & code generation
├── core/             # Core framework classes (Bootstrap, ApiService, Security)
├── http/             # HTTP layer (Request, Response, JWT)
├── database/         # Database layer (ORM, migrations, query builders)
├── helper/           # Utility classes (TypeChecker, FileHelper, CryptHelper)
├── startup/          # Platform-specific initialization files
└── stubs/            # IDE type stubs (OpenSwoole, Redis)

Each directory has a specific purpose and contains related components that work together to provide the framework's functionality.

Core Design Principles

1

Webserver-Agnostic Application Code

The app/ folder code never changes when switching webservers. The framework handles all platform differences, so the same API endpoints work on Apache, OpenSwoole, and Nginx.

2

Automatic Security (90% Automatic)

No configuration needed - Security works out of the box. Path protection, input sanitization, and SQL injection prevention are all automatic. Developers only need to call definePostSchema() and auth() methods.

3

Environment-Aware Architecture

Automatic webserver detection, automatic database manager selection, and automatic request adapter selection. The framework adapts to your environment automatically.

4

Code Generation CLI

Generate Services, Controllers, Models, Tables, and CRUD operations via CLI commands. Template-based generation system with Docker-compose generation support.

Request Flow Architecture

Understanding how requests flow through GEMVC is crucial for building effective applications. The flow differs slightly between Apache/Nginx and OpenSwoole, but your application code remains the same.

Apache/Nginx Flow

HTTP Request
↓
index.php (startup/apache/index.php)
↓
Bootstrap.php → Security check (automatic)
↓
ApacheRequest.php → Sanitize all inputs (automatic)
↓
app/api/User.php → Developer schema validation
↓
UserController.php → Business logic
↓
UserTable.php → Database operations (prepared statements)
↓
JsonResponse.php → Return JSON

OpenSwoole Flow

HTTP Request
↓
OpenSwooleServer.php → Security check (automatic)
↓
SwooleRequest.php → Sanitize all inputs (automatic)
↓
SwooleBootstrap.php → Route to API service
↓
app/api/User.php → Developer schema validation
↓
UserController.php → Business logic
↓
UserTable.php → Database operations (connection pooling)
↓
JsonResponse.php → Return JSON (via showSwoole())

Component Breakdown

GEMVC is organized into several key components, each handling specific responsibilities:

CLI/ - Code Generation & Project Management

Handles command-line interface, code generation, and project initialization.

  • Command.php - Base command class
  • AbstractInit.php - Template method for project initialization
  • CreateService.php, CreateController.php - Code generators

core/ - Framework Core

Core framework classes for routing, security, and request handling.

  • Bootstrap.php / SwooleBootstrap.php - Request routing
  • ApiService.php - Base API service classes
  • SecurityManager.php - Path access protection
  • ApiDocGenerator.php - Auto-generate API documentation

http/ - HTTP Layer

Handles HTTP requests, responses, authentication, and sanitization.

  • Request.php - Unified request object (all inputs sanitized)
  • ApacheRequest.php / SwooleRequest.php - Platform adapters
  • JWTToken.php - JWT creation, verification, renewal
  • Automatic input sanitization (XSS prevention)

database/ - Database Layer

ORM, query builders, migrations, and database management.

  • Table.php - Main ORM class (fluent interface)
  • UniversalQueryExecuter.php - Enforces prepared statements
  • DatabaseManagerFactory.php - Auto-selects DB manager
  • 100% SQL injection prevention (all queries use prepared statements)

helper/ - Utility Classes

Utility classes for type checking, file operations, encryption, and more.

  • TypeChecker.php - Runtime type validation
  • FileHelper.php - File operations + encryption
  • CryptHelper.php - Password hashing (Argon2I) + AES-256-CBC encryption
  • ImageHelper.php - Image processing + signature detection

Security Architecture

GEMVC provides 90% automatic security with no developer configuration needed. Security is built into the framework at every layer.

Automatic Security (No Developer Action)

Path Protection - Blocks /app, /vendor, .env, etc.
Header Sanitization - All HTTP headers sanitized automatically
Input Sanitization - All GET/POST/PUT/PATCH sanitized (XSS prevention)
SQL Injection Prevention - All queries use prepared statements
File Name Sanitization - Uploaded file names sanitized
Cookie Filtering - Dangerous cookies blocked

Developer-Enabled Security (Simple Method Calls)

Schema Validation - Call definePostSchema() (prevents mass assignment)
Authentication - Call $request->auth() (JWT validation)
Authorization - Call $request->auth(['role']) (role checking)

URL-to-Code Mapping

GEMVC automatically maps URLs to code using a simple, predictable pattern:

URL: /api/User/create
↓
Extracts: Service = "User", Method = "create"
↓
Loads: app/api/User.php
↓
Calls: User::create()
↓
User::create() validates schema → delegates to UserController
↓
UserController::create() handles business logic
↓
UserTable::create() performs database operation

Configuration (via .env):

  • SERVICE_IN_URL_SECTION=1 (default: 1)
  • METHOD_IN_URL_SECTION=2 (default: 2)

Performance Features

OpenSwoole Optimizations

  • ✓ Connection pooling (database)
  • ✓ Persistent processes (no PHP bootstrap overhead)
  • ✓ Hot reload (development)
  • ✓ Async capabilities
  • ✓ WebSocket support

Apache/Nginx Optimizations

  • ✓ Optional persistent PDO connections
  • ✓ Cached environment detection
  • ✓ Singleton patterns for managers
  • ✓ Prepared statement reuse

🎉 Architecture Complete!

Now that you understand GEMVC's architecture, let's learn about the request lifecycle!

Next: Request Lifecycle Back to Learning Hub View Technical Docs