usher-manage-stack/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-02-13

Directory Layout

usher-manage-stack/
├── app/                           # Application code
│   ├── Console/Commands/          # Custom Artisan commands
│   ├── Exceptions/                # Exception handlers
│   ├── Http/
│   │   ├── Controllers/           # Web controllers split by domain
│   │   │   ├── Admin/             # Admin panel controllers (10 controllers)
│   │   │   ├── Api/               # API controllers (4 controllers)
│   │   │   ├── Auth/              # Auth controllers
│   │   │   ├── *Controller.php    # Main route controllers
│   │   ├── Middleware/            # HTTP middleware (11 total)
│   │   ├── Requests/              # Form Request validation classes
│   │   └── Resources/             # API response resources
│   ├── Jobs/                      # Queued jobs
│   ├── Mail/                      # Mail classes (notifications)
│   ├── Models/                    # Eloquent models (36 models)
│   ├── Observers/                 # Model observers
│   ├── Providers/                 # Service providers
│   ├── Services/                  # Business logic services (7 services)
│   ├── Support/                   # Helper classes
│   ├── Traits/                    # Shared model traits (2 traits)
│   ├── View/Components/           # Blade components
│   ├── helpers.php                # Global helper functions
│
├── bootstrap/                     # Bootstrap files
├── config/                        # Configuration files
├── database/
│   ├── migrations/                # Database migrations
│   ├── seeders/                   # Database seeders
│   ├── factories/                 # Model factories for testing
│   └── schema/                    # Schema dump
│
├── resources/
│   ├── css/                       # Tailwind CSS
│   ├── views/                     # Blade templates
│   │   ├── admin/                 # Admin panel views (20+ subdirectories)
│   │   ├── auth/                  # Auth views (login, register, etc.)
│   │   ├── components/            # Reusable components
│   │   ├── emails/                # Email templates
│   │   ├── layouts/               # Layout files
│   │   ├── member/                # Member-specific views
│   │   ├── public/                # Public-facing views
│   │   └── profile/               # Profile views
│
├── routes/
│   ├── web.php                    # Web routes (393 lines, 200+ named routes)
│   ├── api.php                    # API routes (v1)
│   ├── auth.php                   # Auth routes
│   ├── console.php                # Console commands
│   └── channels.php               # Broadcasting channels
│
├── storage/
│   ├── app/                       # File uploads (private)
│   ├── logs/                      # Application logs
│   └── framework/                 # Framework files
│
├── tests/                         # Test suite
├── .env.example                   # Environment template
├── CLAUDE.md                      # Project-specific instructions
├── composer.json                  # PHP dependencies
└── artisan                        # Artisan CLI entry point

Directory Purposes

app/Models:

• Purpose: Eloquent models representing database tables
• Contains: 36 models with relationships, scopes, accessors
• Key files:
  • Member.php — Member lifecycle (status, disability, identity type)
  • FinanceDocument.php — Finance approval workflow (27+ status constants)
  • User.php — User authentication and roles
  • MembershipPayment.php — Payment verification workflow
  • Document.php — Document library with versioning
  • Article.php, Page.php — CMS content
  • Issue.php — Issue tracker with comments, attachments, time logs
  • AccountingEntry.php — Double-entry bookkeeping records

app/Http/Controllers:

• Purpose: Handle HTTP requests and coordinate responses
• Contains: 25+ controller classes
• Structure:
  • Admin/ — 10 controllers for admin features (articles, documents, pages, etc.)
  • Api/ — 4 controllers for REST API endpoints
  • Root controllers for public and authenticated routes
• Pattern: Inject dependencies, call services, return view/response

app/Http/Controllers/Admin:

• DocumentController.php — Document CRUD with version control
• ArticleController.php — Article CRUD with publish/archive
• PageController.php — Page CRUD with publish
• AnnouncementController.php — Announcements with pinning
• SystemSettingsController.php — System settings UI
• GeneralLedgerController.php, TrialBalanceController.php — Accounting reports

app/Services:

• Purpose: Encapsulate complex business logic
• Files:
  • FinanceDocumentApprovalService.php — Multi-tier approval orchestration
  • MembershipFeeCalculator.php — Fee calculation with disability discount
  • SettingsService.php — System settings caching/retrieval
  • PaymentVerificationService.php — Payment workflow coordination
  • SiteRevalidationService.php — Next.js static site rebuild webhook
  • SiteAssetSyncService.php, NextjsRepoSyncService.php — Frontend sync

app/Traits:

• Purpose: Shared behavior across multiple models
• HasApprovalWorkflow.php — Multi-tier approval methods (6 methods)
• HasAccountingEntries.php — Double-entry bookkeeping (8 methods)
• Usage: Models add use TraitName; to inherit behavior

app/Http/Requests:

• Purpose: Form request validation classes (implicit validation in controllers)
• Files:
  • StoreMemberRequest.php — Member creation rules
  • UpdateMemberRequest.php — Member update rules
  • StoreFinanceDocumentRequest.php — Finance document rules
  • StoreIssueRequest.php — Issue creation rules
  • ProfileUpdateRequest.php — User profile rules
• Pattern: Define rules() and messages() methods; controller receives validated data

app/Http/Middleware:

• EnsureUserIsAdmin.php — Admin access check (admin role OR any permission)
• Authenticate.php — Session authentication
• CheckPaidMembership.php — Membership status validation
• Standard middleware: CSRF, encryption, trusted proxies

app/Support:

• AuditLogger.php — Static class for centralized audit logging
• DownloadFile.php — File download handler with cleanup
• Usage: AuditLogger::log('action_name', $model, $metadata)

resources/views:

• Purpose: Blade templates rendering HTML
• Structure:
  • admin/ — 20+ directories for admin features
    • admin/finance/ — Finance documents
    • admin/members/ — Member management
    • admin/issues/ — Issue tracker
    • admin/articles/, admin/pages/ — CMS
    • admin/announcements/, admin/documents/ — Announcements and document library
  • auth/ — Login, register, password reset
  • member/ — Member-facing views
  • public/ — Public-facing views
  • layouts/ — Layout templates (app.blade.php, guest.blade.php)
  • components/ — Reusable Blade components

config/:

• accounting.php — Account codes, amount tiers, chart of accounts
• auth.php — Authentication guards, registration enabled flag
• permission.php — Spatie permission defaults
• services.php — External service configuration (Nextjs revalidate URL)
• app.php, database.php, cache.php, etc. — Standard Laravel configs

routes/:

• web.php — All 200+ web routes
  • Public: /, /documents, /register/member (if enabled), /beta/bug-report
  • Auth: /dashboard, /my-membership, /member/submit-payment, /profile
  • Admin: /admin/* with group prefix and admin middleware
• api.php — API v1 routes
  • /api/v1/articles, /api/v1/pages, /api/v1/homepage, /api/v1/public-documents
  • Authentication: Sanctum (optional)
• auth.php — Login, register, password reset routes

Key File Locations

Entry Points:

• public/index.php — Application entry point
• app/Providers/RouteServiceProvider.php — Route registration
• routes/web.php — All web routes
• routes/api.php — API routes

Configuration:

• config/accounting.php — Finance tier thresholds, account codes
• config/auth.php — Registration enabled flag, authentication settings
• config/services.php — External service URLs and tokens
• .env file (not committed) — Environment variables

Core Logic:

• app/Models/FinanceDocument.php — Finance workflow logic (approval, disbursement, recording)
• app/Models/Member.php — Member lifecycle logic (status checks, fees)
• app/Services/FinanceDocumentApprovalService.php — Approval orchestration
• app/Traits/HasApprovalWorkflow.php — Reusable approval behavior
• app/Traits/HasAccountingEntries.php — Reusable accounting behavior

Business Rules:

• app/Services/MembershipFeeCalculator.php — Fee calculation
• app/Services/PaymentVerificationService.php — Payment workflow
• app/Http/Controllers/FinanceDocumentController.php — Finance CRUD and workflow actions
• app/Http/Controllers/AdminMemberController.php — Member CRUD and lifecycle

Testing:

• tests/ — Test suite (PHPUnit)
• Database tests use RefreshDatabase trait
• Test accounts in seeders: admin@test.com, requester@test.com, cashier@test.com, etc.

Database:

• database/migrations/ — 20+ migrations
• database/seeders/ — RoleSeeder, ChartOfAccountSeeder, TestDataSeeder, FinancialWorkflowTestDataSeeder
• database/factories/ — Model factories for testing

Naming Conventions

Files:

• Controllers: PluralCamelCase + Controller.php (e.g., FinanceDocumentController.php)
• Models: SingularCamelCase.php (e.g., FinanceDocument.php)
• Requests: Action + ModelName + Request.php (e.g., StoreFinanceDocumentRequest.php)
• Migrations: YYYY_MM_DD_HHMMSS_action_table_name.php
• Views: snake_case.blade.php (e.g., create.blade.php, edit.blade.php)

Directories:

• Controllers: Group by feature/domain (Admin/, Api/, Auth/)
• Views: Mirror controller structure (admin/, auth/, member/, public/)
• Models: Flat in app/Models/
• Services: Flat in app/Services/
• Migrations: Flat in database/migrations/

Routes:

• Named routes: domain.action (e.g., admin.finance.index, member.payments.store)
• Admin routes: Prefix admin. and grouped under /admin URL prefix
• Public routes: No prefix (e.g., documents.index, register.member)

Database:

• Tables: snake_case plural (e.g., finance_documents, membership_payments)
• Columns: snake_case (e.g., submitted_by_user_id, approved_at)
• Foreign keys: model_id singular (e.g., member_id, user_id)
• Timestamps: created_at, updated_at (auto-managed)
• Encrypted fields: field_encrypted and field_hash for search (e.g., national_id_encrypted, national_id_hash)

Constants:

• Status values: ModelName::STATUS_STATE all caps (e.g., FinanceDocument::STATUS_PENDING)
• Type values: ModelName::TYPE_NAME all caps (e.g., Member::TYPE_INDIVIDUAL)
• Amount tiers: ModelName::AMOUNT_TIER_LEVEL all caps (e.g., FinanceDocument::AMOUNT_TIER_SMALL)

Where to Add New Code

New Feature (CRUD):

• Primary code:

  • Model: app/Models/NewModel.php — Define relationships, scopes, accessors
  • Controller: app/Http/Controllers/Admin/NewModelController.php or root controller
  • Requests: app/Http/Requests/Store/UpdateNewModelRequest.php
  • Views: resources/views/admin/new-models/ with index/create/edit/show
  • Routes: Add to routes/web.php within appropriate middleware group

• Example structure:

  // Model relationships
  public function relationships()
  
  // Form validation in FormRequest
  public function rules()
  
  // Controller action
  public function store(StoreNewModelRequest $request)
  
  // View rendering
  return view('admin.new-models.create', ['data' => ...]);
  

New Component/Module (Multi-Model Feature):

• Implementation:

  • Models: Multiple related models in app/Models/
  • Service: app/Services/NewModuleService.php for complex logic
  • Controller: app/Http/Controllers/NewModuleController.php or Admin/NewModuleController.php
  • Views: resources/views/admin/new-module/ or resources/views/new-module/
  • Routes: Add feature routes to routes/web.php
  • Migrations: Database tables in database/migrations/

• Example: Finance Documents (FinanceDocument → PaymentOrder → CashierLedgerEntry → AccountingEntry)

  // Service orchestrates workflow
  $service->approveBySecretary($document, $user);
  
  // Models track state
  $document->status, $document->disbursement_status, $document->recording_status
  

Utilities/Helpers:

• Shared helpers: app/Support/HelperClass.php or method in app/helpers.php
• Example: AuditLogger::log(), DownloadFile::download()
• Global function: Add to app/helpers.php if used in multiple places
• Config values: Add to appropriate config/ file

New API Endpoint:

• Controller: app/Http/Controllers/Api/ResourceController.php
• Resource: app/Http/Resources/ResourceResource.php for response formatting
• Routes: Add to routes/api.php under prefix('v1')
• Example:

  // routes/api.php
  Route::get('/articles', [ArticleController::class, 'index']);
  
  // app/Http/Controllers/Api/ArticleController.php
  public function index() {
      return ArticleResource::collection(Article::active()->get());
  }
  

New Blade Component:

• File: resources/views/components/component-name.blade.php
• Class (if needed): app/View/Components/ComponentName.php
• Usage: <x-component-name :data="$data" />

New Service:

• File: app/Services/NewService.php
• Usage: Dependency injection in controllers or other services
• Pattern:

  // In controller
  public function action(NewService $service) {
      $result = $service->doSomething();
  }
  

New Trait (Shared Behavior):

• File: app/Traits/HasNewBehavior.php
• Usage: use HasNewBehavior; in models
• Pattern: Define methods that multiple models need

Special Directories

storage/app/:

• Purpose: Private file uploads
• Subdirectories: finance-documents/, articles/, disability-certificates/
• Generated: Yes
• Committed: No (in .gitignore)
• Access: Storage::disk('local')->get($path) or via authenticated controller

database/schema/:

• Purpose: Schema dump for reference
• Generated: By php artisan schema:dump
• Committed: Yes (read-only reference)
• Use: Check table structure without opening migrations

resources/css/:

• Purpose: Tailwind CSS source
• Style: Uses @apply for utility classes
• Config: tailwind.config.js with dark mode class strategy
• Build: npm run build compiles to public/css/app.css

config/:

• Purpose: Application configuration
• Committed: Yes (except .env)
• Environment-specific: Values read from .env via env('KEY', 'default')
• Access: config('key.subkey') in code

tests/:

• Purpose: PHPUnit test suite
• Structure: Mirror app structure (Unit/, Feature/)
• Pattern: RefreshDatabase trait for database reset, use test factories
• Run: php artisan test

---

Structure analysis: 2026-02-13