# Project Structure

## Directory Organization

### `/app` - Application Core
- **`/Filament`** - Admin panel components
  - `/Exports` - Excel export definitions
  - `/Imports` - Excel import definitions
  - `/Pages` - Custom Filament pages
  - `/Resources` - CRUD resources for entities (Branches, Cities, Services, etc.)
  - `/Widgets` - Dashboard widgets
- **`/Http`** - Web layer
  - `/Controllers` - Request handlers for public routes
  - `/Middleware` - Custom middleware (e.g., partial maintenance)
- **`/Imports`** - Data import classes (ShippingRateImport)
- **`/Models`** - Eloquent models (About, Branch, City, District, Province, Village, ShippingRate, etc.)
- **`/Policies`** - Authorization policies for each model
- **`/Providers`** - Service providers

### `/config` - Configuration Files
Laravel and package configuration files

### `/database` - Database Layer
- `/factories` - Model factories for testing
- `/migrations` - Database schema migrations
- `/seeders` - Database seeders

### `/resources` - Frontend Assets
- `/css` - Stylesheets
- `/js` - JavaScript files
- `/views` - Blade templates for public website

### `/routes` - Route Definitions
- `web.php` - Public website routes
- `console.php` - Artisan commands

### `/storage` - Runtime Storage
- `/app/public` - Public file storage (banners, client images, hero banners)
- `/framework` - Framework cache, sessions, views
- `/logs` - Application logs

### `/public` - Web Root
Public assets and entry point

### `/vendor` - Composer Dependencies

## Key Conventions

### Models
- Located in `app/Models`
- Use `$guarded = []` for mass assignment protection
- Include relationships (e.g., `creator()` BelongsTo User)
- Follow singular naming (Branch, City, Service)

### Filament Resources
- Organized in `app/Filament/Resources/{EntityName}s/`
- Each resource manages CRUD operations for a model
- Policies control access via Filament Shield

### Controllers
- Located in `app/Http/Controllers`
- Named with entity + "Controller" suffix
- Handle public-facing routes (HomeController, TrackingController, etc.)

### Routes
- Public routes in `routes/web.php`
- Use route names for all routes (e.g., `->name('home')`)
- Group related routes with prefixes (e.g., `tracking.*`)
- Legacy redirects included for old URLs

### Views
- Blade templates in `resources/views`
- Follow Laravel naming conventions

### Database
- SQLite default (file: `database/database.sqlite`)
- Migrations use standard Laravel schema builder
- Location hierarchy: Province → City → District → Village

### File Storage
- Media files managed by Spatie Media Library
- Public uploads in `storage/app/public/`
- Categories: hero-banners, client-images, banners

## Naming Patterns
- **Models**: Singular PascalCase (Branch, ShippingRate)
- **Tables**: Plural snake_case (branches, shipping_rates)
- **Controllers**: PascalCase + Controller suffix
- **Routes**: kebab-case with dot notation for names
- **Views**: kebab-case.blade.php
