# Project Structure

This document summarizes the main folders, key entry points, and how the codebase is organized.

## Top-Level Layout

- `app/` - Core application code (Laravel).
- `bootstrap/` - Framework bootstrap and cache files.
- `config/` - Application configuration.
- `database/` - Migrations, seeders, factories, and source data.
- `docs/` - Internal documentation.
- `lang/` - Localization files (AR/EN).
- `modules/` - Modular packages (see Payment module below).
- `public/` - Public web root and built assets.
- `resources/` - Views, JS, and CSS sources.
- `routes/` - Route definitions.
- `storage/` - Logs, cache, and file uploads.
- `tests/` - Automated tests.
- `vendor/` - Composer dependencies.

## Core Application (`app/`)

- `app/Console/` - Artisan commands and scheduling.
- `app/Http/Controllers/` - HTTP controllers organized by API surface.
- `app/Http/Middleware/` - Request middleware (auth, locale, permissions).
- `app/Http/Resources/` - API response transformers.
- `app/Models/` - Eloquent models.
- `app/Services/` - Business logic and service layer.
- `app/Enums/` - Enum definitions for types and settings.
- `app/Traits/` - Shared behavior for models and services.
- `app/Helpers/` - Global helper functions.
- `app/Notifications/`, `app/Mail/`, `app/Jobs/` - Messaging, mail, and queue jobs.
- `app/Observers/`, `app/Policies/` - Model observers and authorization rules.

## Routes (`routes/`)

- `routes/api/client.php` - Client-facing API endpoints.
- `routes/api/admin.php` - Admin dashboard API endpoints.
- `routes/api/general.php` - Public API endpoints.
- `routes/web.php` - Web routes (minimal for API-first projects).

## Resources (`resources/`)

- `resources/views/` - Blade templates used by admin or module views.
- `resources/js/` - Frontend JS entry points.
- `resources/css/` - Frontend styles.

## Database (`database/`)

- `database/migrations/` - Core schema migrations.
- `database/seeders/` - Seed data and initial setup.
- `database/factories/` - Model factories for tests.
- `database/sources/` - Reference data sources used during seeding.

## Payment Module (`modules/Payment/`)

The Payment module is a self-contained package-like structure with its own routes, config, migrations, tests, and resources.

- `modules/Payment/src/` - Module code (controllers, services, models, gateways).
- `modules/Payment/routes/` - Payment API routes.
- `modules/Payment/config/` - Module configuration.
- `modules/Payment/database/migrations/` - Module-specific schema.
- `modules/Payment/resources/` - Module views and assets.
- `modules/Payment/tests/` - Module test suite.
- `modules/Payment/payment_images/` - Static gateway assets.

## Other Key Files

- `artisan` - Laravel CLI entry point.
- `composer.json` - PHP dependencies and scripts.
- `package.json` - Frontend tooling and scripts.
- `vite.config.js` - Vite build configuration.
- `phpunit.xml` - Test configuration.
- `postman_collection.json` - API testing collection.
- `queue.yml` and `schadule.yml` - Deployment/queue scheduling helpers.

## Notes

- The architecture follows a service-layer pattern: Controllers delegate business logic to services, which coordinate models and helpers.
- The Payment module is isolated for easy extraction or reuse in other Laravel projects.