Skip to main content

Architecture

System architecture and project structure documentation for ZÈYA API.

Tech Stack​

Core Framework​

  • Framework: Laravel 10.10
  • PHP: 8.1+
  • Authentication: JWT (tymon/jwt-auth) + Laravel Sanctum
  • API Versioning: v1

Databases​

  • Primary Database: MySQL/PostgreSQL
  • Secondary Database: MongoDB (product search/indexing)
  • Cache/Queue: Redis

File Storage​

  • File Storage: AWS S3
  • Image Processing: Intervention Image

External Services​

  • Firebase: Realtime Database, Analytics, Cloud Messaging
  • Google BigQuery: Analytics and data warehousing
  • Google Cloud Storage: File storage
  • Expo Push Notifications: Mobile push notifications
  • Twilio: SMS/OTP services
  • Apple App Store Connect API: App release monitoring
  • Google Play Developer API: App release monitoring

Development Tools​

  • Code Quality: Laravel Pint
  • Testing: PHPUnit
  • Queue System: Laravel Queue (Redis)

Project Structure​

api/
├── app/
│   ├── Casts/                    # Custom Eloquent casts
│   ├── Console/
│   │   └── Commands/             # Artisan commands
│   ├── Exceptions/
│   │   └── Handler.php          # Exception handler
│   ├── Guards/                  # Custom authentication guards
│   ├── Http/
│   │   ├── Controllers/         # API controllers (30+)
│   │   ├── Middleware/          # Custom middleware
│   │   ├── Requests/            # Form request validation
│   │   └── Resources/           # API resources (transformers)
│   ├── Jobs/                    # Queue jobs
│   ├── Models/                  # Eloquent models (50+)
│   ├── Providers/               # Service providers
│   └── Services/                # Business logic services
│
├── routes/
│   ├── api.php                  # API routes (v1 & admin)
│   ├── channels.php             # Broadcasting channels
│   ├── console.php              # Artisan commands
│   └── web.php                  # Web routes
│
├── database/
│   ├── migrations/              # Database migrations (120+)
│   ├── factories/               # Model factories
│   └── seeders/                 # Database seeders
│
├── config/                      # Configuration files
├── tests/                       # PHPUnit tests
├── storage/                     # File storage
├── docker/                      # Docker configuration
└── public/                      # Public assets

Architecture Patterns​

MVC with Service Layer​

The application follows Laravel's MVC pattern with an additional Service layer:

Controller → Service → Model → Database

Controllers (app/Http/Controllers/)

  • Handle HTTP requests/responses
  • Thin layer that delegates to Services
  • Use Form Requests for validation
  • Return API Resources

Services (app/Services/)

  • Contain business logic
  • Handle complex operations
  • Coordinate between multiple models
  • Manage transactions

Models (app/Models/)

  • Eloquent ORM models
  • Define relationships
  • Include scopes and accessors
  • Handle data access

Request Flow​

  1. Request → Route → Middleware
  2. Middleware → Authentication, Authorization, Validation
  3. Controller → Receives request, validates via Form Request
  4. Service → Business logic execution
  5. Model → Database operations
  6. Resource → Response transformation
  7. Response → JSON response to client

Database Architecture​

Primary Database (MySQL/PostgreSQL)​

Stores all relational data:

  • Users, Products, Transactions
  • Groups, Messages, Notifications
  • Settings, Preferences, Activity Logs

Secondary Database (MongoDB)​

Used for:

  • Product search indexing
  • Full-text search
  • Geospatial queries

Authentication Architecture​

JWT Authentication​

  • Uses tymon/jwt-auth package
  • Tokens stored client-side
  • Refresh token mechanism
  • Token expiration: 60 minutes (configurable)

Sanctum Authentication​

  • Used for admin panel
  • Token-based authentication
  • SPA authentication support

API Architecture​

Versioning​

All endpoints are versioned:

  • /api/v1/ - Main API endpoints
  • /api/admin/v1/ - Admin API endpoints
  • /api/service/ - Service-to-service API

Response Format​

Consistent JSON response structure:

{
  "success": true|false,
  "data": { ... },
  "message": "Optional message",
  "errors": { ... } // For validation errors
}

Queue Architecture​

Queue System​

  • Uses Redis as queue driver
  • Multiple queues: high, default, low
  • Failed jobs stored in database
  • Retry mechanism with exponential backoff

Common Jobs​

  • GenerateProductDataset - Product indexing
  • SendBulkNotifications - Push notifications
  • ProcessProductImages - Image processing

Caching Strategy​

Cache Layers​

  1. Application Cache (Redis)

    • Configuration cache
    • Route cache
    • View cache

  2. Query Cache

    • Frequently accessed data
    • Expensive queries
    • Tagged cache for invalidation

  3. CDN Cache (for static assets)

    • Images
    • CSS/JS files

File Storage Architecture​

AWS S3​

  • Product images
  • User profile pictures
  • Chat media files
  • Group images

Storage Structure​

s3://bucket/
├── products/
│   └── {product_id}/
│       └── {image_name}.jpg
├── users/
│   └── {user_id}/
│       └── profile.jpg
└── chat/
    └── {chat_id}/
        └── {media_file}

Security Architecture​

Authentication​

  • JWT tokens with expiration
  • Refresh token rotation
  • OTP verification for sensitive operations

Authorization​

  • Role-based access control (RBAC)
  • Policy-based authorization
  • Middleware for route protection

Data Protection​

  • Input validation via Form Requests
  • SQL injection prevention (Eloquent ORM)
  • XSS protection
  • CSRF protection for web routes

Monitoring & Logging​

Logging​

  • Laravel logging to files
  • Error tracking
  • Activity logging for audit trail

Monitoring​

  • Health check endpoint (/api/health)
  • Queue monitoring
  • Database query monitoring
  • Performance metrics