API Requirements by View

Last Updated: November 19, 2025 Purpose: Map each view to required backend API endpoints

---

📊 Summary

Type	Count	Description
Full CRUD APIs	15 views	Create, Read, Update, Delete operations
Read-Only APIs	8 views	Display data, no mutations
Authentication APIs	6 views	Laravel Breeze/Fortify (built-in)
Frontend-Only	1 view	No backend needed

Total Views: 30

---

🔐 Authentication & Onboarding (Laravel Breeze/Fortify)

✅ Built-in Laravel APIs (No Custom Development Needed)

20. Admin Login

• POST /login - Authenticate user
• POST /logout - End session
• Laravel Breeze: ✅ Included

21. Crew Login

• Same endpoints as Admin Login (different subdomain)
• Laravel Breeze: ✅ Included

22. Forgot Password

• POST /forgot-password - Send reset link
• Laravel Fortify: ✅ Included

23. Reset Password

• POST /reset-password - Update password with token
• Laravel Fortify: ✅ Included

24. Email Verification

• GET /verify-email/{id}/{hash} - Verify email
• POST /email/verification-notification - Resend verification
• Laravel Fortify: ✅ Included

28. Admin User Profile

• GET /user/profile - Get current user
• PUT /user/profile-information - Update profile
• PUT /user/password - Change password
• Laravel Fortify: ✅ Included (basic)
• Custom Needed: Preferences, session management (optional for MVP)

---

🏢 Company & User Management

25. Company Registration (Self-Service)

Priority: 🟡 If time allows

API Endpoints Needed:

POST /register
  Request: {
    company: { name, org_number, base_currency, country },
    user: { name, email, password, password_confirmation }
  }
  Response: { message, requires_verification: true }

  Creates:
  - companies record
  - users record (ADMIN role)
  - Sends verification email

Alternative for MVP: PBS admin creates records manually in database

---

26. Initial Setup Wizard

Priority: 🟡 If time allows

API Endpoints Needed:

PUT /setup/company-details
  Request: { logo, phone, address, website }
  Updates: companies record

POST /setup/contract-template
  Request: { general_contract_template }
  Updates: companies.general_contract_template

POST /setup/import-global-functions
  Request: { global_function_ids: [] }
  Creates: functions_catalog records

POST /setup/invite-team
  Request: { users: [{ name, email, role }] }
  Creates: users records + sends invites

GET /setup/status
  Response: { completed_steps: [], current_step }

Alternative for MVP: Skip wizard, configure via Company Settings (#13)

---

27. User Management

Priority: 🟡 If easy

API Endpoints Needed:

GET /api/users
  Query: ?role=ADMIN&status=active
  Response: { data: [users], meta: { total, page } }

POST /api/users/invite
  Request: { name, email, role }
  Creates: users record + sends invitation email

PUT /api/users/{id}
  Request: { name, email, role }
  Updates: users record

DELETE /api/users/{id}
  Validation: Cannot delete self, cannot delete last admin
  Soft deletes: users record

POST /api/users/{id}/suspend
  Updates: users.deleted_at (soft delete)

POST /api/users/{id}/activate
  Restores: users record

Alternative for MVP: PBS admin creates users manually

---

29. Super Admin Dashboard

Priority: ⏭️ Post-MVP

API Endpoints Needed:

GET /admin/companies
  Response: { data: [companies with stats] }

POST /admin/companies
  Request: { name, org_number, website, base_currency, ... }

PUT /admin/companies/{id}
DELETE /admin/companies/{id}
POST /admin/companies/{id}/suspend

GET /admin/stats
  Response: { total_companies, total_users, active_projects, ... }

Not Needed for MVP: Manual management initially

---

30. Billing & Subscription

Priority: ⏭️ Post-MVP

API Endpoints Needed:

GET /api/billing/subscription
  Response: { plan, price, features, billing_cycle }

POST /api/billing/change-plan
  Request: { plan_id }

GET /api/billing/payment-method
POST /api/billing/payment-method

GET /api/billing/invoices
  Response: { data: [invoices] }

GET /api/billing/invoices/{id}/download
  Returns: PDF file

GET /api/billing/usage
  Response: { users_count, projects_count, storage_used, limits }

MVP: Handle outside system (manual invoicing)

---

🎨 Backend Portal - Core Operations

1. Dashboard (Home)

Priority: ✅ MVP

API Endpoints Needed:

GET /api/dashboard/stats
  Response: {
    active_projects: 5,
    pending_offers: 12,
    available_crew: 48,
    this_month_budget: 125000,
    recent_activity: [],
    upcoming_assignments: []
  }

Dependencies: Projects, assignments, assignment_offers, crew

---

2. Projects List

Priority: ✅ MVP

API Endpoints Needed:

GET /api/projects
  Query: ?status=active&sort=date&search=Champions
  Response: {
    data: [
      {
        id, project_code, name, status, start_date, end_date,
        location_city, budget_cents, budget_currency,
        crew_count, assignments_count
      }
    ],
    meta: { total, per_page, current_page }
  }

---

3. Project Details

Priority: ✅ MVP

API Endpoints Needed:

GET /api/projects/{id}
  Response: {
    project: { full project data },
    crew_assignments: [],
    equipment_bookings: [],
    budget_summary: {},
    documents: [],
    communication_log: []
  }

PUT /api/projects/{id}
  Request: { name, dates, location, budget, ... }

DELETE /api/projects/{id}
  Soft delete

POST /api/projects/{id}/finalize-financials
  Updates: financials_finalized = true

Sub-Resources:

GET /api/projects/{id}/crew
GET /api/projects/{id}/equipment
GET /api/projects/{id}/budget
GET /api/projects/{id}/documents
GET /api/projects/{id}/communications

---

4. Crew Directory

Priority: ✅ MVP

API Endpoints Needed:

GET /api/crew
  Query: ?employment=all&functions=camera&search=Lisa&favorites=true
  Response: {
    data: [
      {
        crew_profile: { id, first_name, last_name, ... },
        company_relationship: {
          is_favorite, private_notes,
          employment_status, primary_functions
        },
        availability_status: 'available|busy'
      }
    ],
    meta: { total, page }
  }

POST /api/crew/{id}/toggle-favorite
  Updates: company_crew.is_favorite

---

5. Crew Profile (View/Edit)

Priority: ✅ MVP

API Endpoints Needed:

GET /api/crew/{id}
  Response: {
    profile: { full crew_profile data },
    company_relationship: { private_notes, is_favorite },
    assignments_history: [],
    availability: [] (if staff),
    documents: []
  }

PUT /api/crew/{id}/profile
  Request: { first_name, last_name, phone, ... }
  Updates: crew_profiles

PUT /api/crew/{id}/company-notes
  Request: { private_notes }
  Updates: company_crew.private_notes

POST /api/crew/{id}/availability
  Request: { start_date, end_date, status, notes }
  Creates: crew_availability (staff only)

DELETE /api/crew/{id}/availability/{availability_id}

---

6. Add/Invite Crew

Priority: ✅ MVP

API Endpoints Needed:

POST /api/crew
  Request: {
    first_name, last_name, email, phone,
    functions: [],
    employment_status: 'staff|freelancer',
    send_invitation: true|false
  }
  Creates: crew_profile + company_crew relationship
  Optionally: Sends invitation email

POST /api/crew/invite
  Request: { email }
  For existing crew in system, creates company_crew link
  For new crew, creates crew_profile + sends invite

---

7. Send Assignment Offer

Priority: ✅ MVP

API Endpoints Needed:

POST /api/projects/{project_id}/offers
  Request: {
    crew_profile_id,
    project_function_id,
    role_note, team_label,
    work_days, travel_days,
    work_day_rate_cents, travel_day_rate_cents, rate_currency,
    start_date, end_date,
    personal_message,
    is_direct_booking: false
  }
  Creates: assignment_offers
  If is_direct_booking=true: Also creates assignment

GET /api/crew/search
  Query: ?q=Lisa&project_id=123
  Response: {
    data: [crew with availability warnings]
  }
  Used for: Autocomplete crew selection

---

8. Offer Management

Priority: ✅ MVP

API Endpoints Needed:

GET /api/offers
  Query: ?status=pending&project_id=123
  Response: { data: [offers with crew and project info] }

GET /api/offers/{id}
  Response: { offer with full details }

PUT /api/offers/{id}
  Request: { rates, dates, message, ... }
  Updates: assignment_offers

POST /api/offers/{id}/confirm
  Creates: assignment from accepted offer
  Updates: assignment_offers.status = 'converted'

POST /api/offers/{id}/withdraw
  Updates: assignment_offers.status = 'withdrawn'

DELETE /api/offers/{id}

---

9. Equipment Management

Priority: ✅ MVP

API Endpoints Needed:

GET /api/equipment
  Response: { data: [company_equipment with availability] }

POST /api/equipment
  Request: { name, default_rate_cents, notes }
  Creates: company_equipment

PUT /api/equipment/{id}
DELETE /api/equipment/{id}

POST /api/projects/{project_id}/equipment
  Request: {
    company_equipment_id,
    start_date, end_date,
    rate_cents (overrides default)
  }
  Creates: project_equipment
  Validates: No conflicts with other bookings

DELETE /api/projects/{project_id}/equipment/{id}

GET /api/equipment/{id}/availability
  Query: ?start_date=2025-05-01&end_date=2025-05-10
  Response: { available: true|false, conflicts: [] }

---

10. Global Functions Management

Priority: ✅ MVP

API Endpoints Needed:

GET /api/global-functions
  Response: { data: [global_functions] }

GET /api/functions
  Response: {
    data: [
      {
        id, name, description,
        global_function_id (if based on global),
        default_work_rate_cents, default_travel_rate_cents,
        is_custom: true|false
      }
    ]
  }

POST /api/functions
  Request: {
    global_function_id (optional),
    name, description,
    default_work_rate_cents, default_travel_rate_cents
  }
  Creates: functions_catalog

PUT /api/functions/{id}
DELETE /api/functions/{id}

POST /api/functions/import-global
  Request: { global_function_ids: [] }
  Creates: Multiple functions_catalog from global_functions

---

11. Calendar View

Priority: ✅ MVP

API Endpoints Needed:

GET /api/calendar/assignments
  Query: ?start=2025-05-01&end=2025-05-31&crew_id=123&project_id=456
  Response: {
    data: [
      {
        id, type: 'assignment|availability|equipment',
        title, start_date, end_date,
        crew_name, project_name,
        status, color
      }
    ]
  }

  Combines:
  - assignments (crew bookings)
  - crew_availability (staff availability)
  - project_equipment (equipment bookings)

Frontend-Only Features:

• Calendar rendering (FullCalendar or similar)
• Month/week/day view switching
• Drag-and-drop (optional)

---

12. Reports

Priority: ✅ MVP

API Endpoints Needed:

GET /api/reports/crew-list
  Query: ?project_id=123&format=pdf
  Returns: PDF or JSON

GET /api/reports/budget
  Query: ?project_id=123&format=excel
  Returns: Excel or JSON

GET /api/reports/meal-list
  Query: ?project_id=123&date=2025-05-15
  Returns: PDF or JSON

GET /api/reports/availability
  Query: ?start_date=2025-05-01&end_date=2025-05-31
  Returns: JSON or Excel

GET /api/reports/financial-summary
  Query: ?project_id=123
  Response: {
    crew_costs: { planned, actual },
    equipment_costs: {},
    budget_items: {},
    total: {},
    breakdown_by_function: []
  }

Report Generation:

• Can use libraries like Laravel Excel, DomPDF
• Or return JSON and generate PDFs in frontend

---

13. Company Settings

Priority: ✅ MVP

API Endpoints Needed:

GET /api/company
  Response: {
    id, name, org_number, base_currency,
    general_contract_template,
    settings: { locale, timezone, ... }
  }

PUT /api/company
  Request: { name, phone, address, base_currency, ... }
  Updates: companies

PUT /api/company/contract-template
  Request: { general_contract_template }
  Updates: companies.general_contract_template

GET /api/exchange-rates
  Response: { data: [exchange_rates] }

POST /api/exchange-rates
  Request: { from_currency, to_currency, rate }
  Creates: exchange_rates

PUT /api/exchange-rates/{id}
DELETE /api/exchange-rates/{id}

---

👥 Crew Portal Views

14. Crew Dashboard

Priority: ✅ MVP

API Endpoints Needed:

GET /api/crew/dashboard
  Response: {
    upcoming_assignments: [],
    pending_offers: [],
    recent_communications: [],
    profile_completion: 85
  }

  Auth: crew_users (based on logged-in crew)

---

15. Assignment Offers (Crew View)

Priority: ✅ MVP

API Endpoints Needed:

GET /api/crew/offers
  Query: ?status=pending&company_id=123
  Response: { data: [offers with project details] }

POST /api/crew/offers/{id}/accept
  Request: { contract_accepted_at } (for freelancers)
  Updates: assignment_offers.status = 'accepted'
  Creates: communication_logs entry

POST /api/crew/offers/{id}/decline
  Request: { reason (optional) }
  Updates: assignment_offers.status = 'declined'

POST /api/crew/offers/{id}/negotiate
  Request: {
    counter_work_rate_cents,
    counter_travel_rate_cents,
    staff_response
  }
  Updates: assignment_offers.status = 'negotiating'

---

16. Assignment Details (Crew View)

Priority: ✅ MVP

API Endpoints Needed:

GET /api/crew/assignments/{id}
  Response: {
    assignment: { full details },
    project: { name, dates, location, client, ... },
    travel_bookings: [],
    hotel_bookings: [],
    documents: []
  }

Read-Only: Crew cannot edit assignments (admin-only)

---

17. Profile Settings (Crew View)

Priority: ✅ MVP

API Endpoints Needed:

GET /api/crew/profile
  Response: {
    crew_user: { email, employer_id },
    profiles: [
      {
        crew_profile: { first_name, last_name, capabilities, ... },
        company: { id, name }
      }
    ]
  }
  Multi-company: Shows all crew_profiles claimed by this crew_user

PUT /api/crew/profile
  Request: {
    first_name, last_name, phone, capabilities,
    emergency_contact, food_preferences, ...
  }
  Updates: ALL crew_profiles for this crew_user
  (Data synced across companies)

PUT /api/crew/password
  Request: { current_password, new_password }
  Updates: crew_users.password

---

18. Crew Registration Flow (Invite Accept)

Priority: ✅ MVP

API Endpoints Needed:

GET /api/crew/register/{token}
  Validates invitation token
  Response: {
    crew_profile: { email, first_name, last_name },
    company: { name }
  }

POST /api/crew/register/{token}
  Request: {
    password, password_confirmation,
    phone, capabilities, ...
  }
  Creates: crew_users record
  Updates: crew_profiles.claimed_by_user_id
  Sends: Email verification

---

19. Communication History (Crew View)

Priority: ✅ MVP

API Endpoints Needed:

GET /api/crew/communications
  Query: ?company_id=123&type=offer
  Response: {
    data: [
      {
        id, type, subject, preview,
        company, status,
        created_at
      }
    ]
  }

GET /api/crew/communications/{id}
  Response: { full message content }

Read-Only: Crew views communication log

---

📊 API Complexity Summary

High Complexity (Full CRUD + Business Logic)

Projects (3)

• Project Details (#3) - Complex with sub-resources
• Send Assignment Offer (#7) - Conflict detection, direct booking
• Offer Management (#8) - Workflow state management

Crew Management (6)

• Crew Directory (#4) - Multi-company relationships
• Crew Profile (#5) - Availability, documents, history
• Add/Invite Crew (#6) - Account claiming workflow
• Equipment Management (#9) - Availability conflicts
• Global Functions (#10) - Import from global catalog
• Calendar View (#11) - Multiple data sources

---

Medium Complexity (Standard CRUD)

8 Views

• Projects List (#2)
• Company Settings (#13)
• Reports (#12) - PDF generation
• User Management (#27)
• Company Registration (#25)
• Crew Dashboard (#14)
• Assignment Offers (Crew) (#15)
• Profile Settings (Crew) (#17)

---

Low Complexity (Read-Only or Simple Updates)

7 Views

• Dashboard (#1) - Read-only stats
• Assignment Details (Crew) (#16) - Read-only
• Communication History (#19) - Read-only
• Admin User Profile (#28) - Simple updates
• Setup Wizard (#26) - Sequential updates
• Crew Registration (#18) - One-time flow
• Super Admin (#29) - Post-MVP

---

Zero Backend (Frontend-Only)

1 View

• Billing & Subscription (#30) - Handled outside system for MVP

Authentication (6 views) - Laravel Breeze/Fortify (built-in, minimal custom code)

---

🔧 Technology Recommendations

API Framework

• Laravel 11 with API Resources
• RESTful architecture
• JSON responses
• API Versioning: /api/v1/... (future-proof)

Authentication

• Laravel Sanctum for SPA authentication
• Session-based for backend portal
• Token-based for crew mobile app (future)

File Handling

• Laravel Storage (S3 or local)
• Signed URLs for secure downloads
• PDF Generation: DomPDF or wkhtmltopdf

Report Generation

• Laravel Excel for Excel exports
• Blade templates for PDFs
• Background Jobs for large reports

Real-Time (Optional for MVP)

• Laravel Echo + Pusher for notifications
• WebSockets for live updates (post-MVP)

---

📋 Development Checklist

Phase 1: Authentication (Week 1)

• Install Laravel Breeze
• Customize auth views (admin + crew portals)
• Setup multi-subdomain routing
• Email verification flow

Phase 2: Core Backend APIs (Weeks 2-4)

• Projects CRUD
• Crew management
• Functions catalog
• Assignment offers workflow

Phase 3: Crew Portal APIs (Week 5)

• Crew dashboard
• View/accept offers
• Profile management
• Registration flow

Phase 4: Advanced Features (Weeks 6-8)

• Equipment management
• Calendar integration
• Reports generation
• Communication logs

Phase 5: Admin Workflow (Week 9)

• Admin task tracking
• Favorite crew
• Contract acceptance
• Travel copy helpers (frontend)

---

🎯 API Development Priority

Sprint 1 (Must Have)

1. Authentication (Laravel Breeze)
2. Projects CRUD
3. Crew CRUD
4. Assignment Offers
5. Admin User Profile

Sprint 2 (Core Features)

6. Crew Dashboard
7. Accept/Decline Offers (Crew)
8. Functions Catalog
9. Company Settings
10. Equipment Management

Sprint 3 (Enhanced Features)

11. Calendar View
12. Reports
13. Communication History
14. Profile Settings (Crew)
15. Crew Registration

Sprint 4 (Optional for MVP)

16. User Management
17. Setup Wizard
18. Company Registration

---

Document Status: ✅ Complete Last Updated: 2025-11-11 Next Review: Development kickoff