2. API Architecture (Route Verified)

This API documentation is aligned with routes/api.php. Base group is /api/v1, with clear separation between public, protected, and backoffice routes.

Base and Security Layers

• Base prefix: /api/v1
• Primary auth guard: auth:api
• Rate limit: throttle:api
• Feature gates: feature.access:{feature_code} on selected modules.

Top-Level Route Segments

1. Public routes: no auth required (login, password reset, landing content, public translations).
2. Backoffice routes: /api/v1/backoffice/* with auth:api + throttle:api.
3. Protected app routes: authenticated operational APIs (inventory, invoice, reports, settings, backup, logs).

Public Routes

System and Auth

GET    /api/v1/install-status
POST   /api/v1/login
POST   /api/v1/forgot-password/request
POST   /api/v1/forgot-password/verify
POST   /api/v1/forgot-password/reset
POST   /api/v1/register-company

Preferences and Translations

GET    /api/v1/preferences
GET    /api/v1/get-company-preferences
GET    /api/v1/translations/{code?}
GET    /api/v1/translation-languages
POST   /api/v1/translations/missing-key

Landing and CMS Public

GET    /api/v1/home
GET    /api/v1/landing/settings
GET    /api/v1/landing/menu
GET    /api/v1/landing/sections/hero
GET    /api/v1/landing/sections/footer
GET    /api/v1/landing/sections/pricing
GET    /api/v1/landing/sections/blog
GET    /api/v1/landing/blogs/{slug}
POST   /api/v1/landing/contact
POST   /api/v1/landing/newsletter/subscribe
GET    /api/v1/pages/{slug}

Backoffice Route Architecture (/api/v1/backoffice)

All backoffice routes are inside:

Route::prefix('backoffice')->middleware(['auth:api','throttle:api'])->group(...)

Backoffice Modules

• Dashboard and feature options: /dashboard, /feature-preferences.
• Role and Company management including rights/feature sync and impersonation.
• Languages management + download/upload translation JSON.
• SaaS plans, admin settings, configurations, email templates, gateways, plan payment logs.
• Currencies and content management (pages, sections, menus).
• Blog categories, blogs, contact messages, newsletters.

Backoffice Company Special Endpoints

GET    /api/v1/backoffice/companies/{id}/users
GET    /api/v1/backoffice/companies/{id}/feature-preferences
PUT    /api/v1/backoffice/companies/{id}/feature-preferences/sync
GET    /api/v1/backoffice/companies/{id}/rights
PUT    /api/v1/backoffice/companies/{id}/rights
POST   /api/v1/backoffice/companies/{id}/users/{userId}/impersonate

Protected Operational Routes (auth:api + throttle:api)

Identity, Profile, Rights

POST   /api/v1/verify-token
POST   /api/v1/verify-route-access
GET    /api/v1/me
GET    /api/v1/user/rights
POST   /api/v1/update/profile
POST   /api/v1/change/password
POST   /api/v1/logout

Plans and Notifications

GET    /api/v1/plans/available
GET    /api/v1/plans/gateways
POST   /api/v1/plans/select
GET    /api/v1/plans/payment-checkout/{id}
GET    /api/v1/notifications
POST   /api/v1/notifications/mark-all-read

Inventory Core Modules

• Users/Customers: /users, /user/*, /search/customers, /customer/store.
• Product setup: category, brand, units, product, variants, segments, bundles.
• Warehouse and supplier: /warehouses*, /suppliers*.
• Barcode store and waitlists.

Invoice and Stock Flow

• Purchase: /purchases*, purchase return/payment, stock-in list.
• Sales: /sales*, drafts, coupon/gift verification, installment pay, invoice email send.
• Stock: /stock/out, /stock/movements.
• Stock Guard: options, rules, request create/approve/reject.
• Stock Transfer: list, source-items, create, transfer report.

Reports and Settings

• Reports: daily/monthly sales-purchase, supplier, category-wise stock/sales, expire, profit margin, accounting, due payments, product ledger, timesheet, return verification.
• Rewards setup and discount setup modules.
• Role-right management and POS settings.
• Timesheet + cash handover + work slots.
• Logs, audit logs, and backup API set.

Feature-Gated API Modules

Response Contract Guidelines

• Keep standardized payload with status, message, and data.
• Validation errors should return field-level error map for frontend forms.
• For list APIs, include consistent pagination metadata where applicable.

Developer Notes (Important)

1. All examples here are rooted at /api/v1; do not document non-versioned paths for this project.
2. When adding new module routes, place them inside the protected group unless explicitly public.
3. If feature gated, use feature.access middleware directly at controller group level.
4. Any route name/method change must be synced with React API clients under frontend-source/src/api.

Source of Truth

Verified against: routes/api.php in this repository.