---
description: Maestro CORE package layout, bootstrap, config, testing
alwaysApply: true
---

# Maestro CORE (this repo: `maestro/core`)

Composable **Laravel + Vue + PrimeVue** SPA shipped as a package. Consumers register `Maestro\Core\Providers\CoreServiceProvider` from their app.

## Layout (high signal)

| Area | Purpose |
|------|---------|
| `src/` | PHP: `Maestro\Core\…` (`declare(strict_types=1);`, PHP ^8.3) |
| `routes/core.php` | Web/session + `api/*` CORE routes |
| `routes/modules/*.php` | Optional modules (registered by module providers) |
| `src/Modules/{Name}/` | Feature modules (example: Customers) |
| `resources/js/` | Vue SPA: `bootCore`, router, layouts, composables |
| `stubs/` | Host app scaffolding; **AutoSyncPackageStubs** + `CoreInstallCommand`: only overwrite host files marked `@maestro-core-managed` |
| `config/core.php` | Merged as `config('core.*')` — **`modules.*` booleans** gate PHP providers |
| `lang/` | Translation namespace `maestro` → `__('maestro::…')` |
| `database/migrations/` | Package migrations |
| `tests/` | PHPUnit (package root); SQLite in-memory defaults in `phpunit.xml` |

## Runtime behavior

- **`CoreServiceProvider`**: merges `core` + `datatable`, registers **DataTables** provider, binds route `user` via `AuthUserResolver` (aligns with host `auth.providers.users.model`).
- **`/api/user`**: Built by `AuthenticatedUserApiPayload` — includes **`enabled_module_slugs`** (from DB modules) alongside Spatie permission/role names when available.
- **Superadmin APIs**: Prefixed `/api/superadmin/*`; middleware `EnsurePlatformSuperadmin`; permission convention including `platform.superadmin`.
- **Microsoft SSO**: SocialiteProviders Microsoft listener wired in CORE.

For **module anatomy** see `maestro-php-backend.mdc` and **`maestro-vue-spa.mdc`**. For **end-to-end steps when adding a new module** (config, migrate, seed, Superadmin, installation health), see **`maestro-module-rollout-workflow.mdc`**. For **DataTables/export/Reverb**, see docs `docs/datatable-export-and-reverb.md` when changing related code.

## Organization (company profile)

- **`organizations` table**: one **company / legal profile** per deployment (Settings › Organization). It is **not** a multi-tenant parent: **no** `organization_id` on `users` or `customers`.
- **`Organization::instance()`**: first row by `id` — used by **`/api/organization`** after permission checks. Seeders (e.g. `UserSeeder`) should ensure at least one row exists.
- **Hosting model**: each end-customer runs their **own** app instance and database; isolation is by deployment, not by a tenant column in Maestro CORE.
