# Claude Code — AdminApp (Landlord / Central Area)

> This is the platform-level app. It is NOT tenant-scoped.
> All models here use the `central` DB connection — never the tenant connection.

---

## What This App Is

The Super Admin control plane. Manages tenants, packages, features, subscriptions, and platform settings. Runs as a separate Laravel app from the tenant app.

---

## ⚠️ Frontend Rules

All UI component and design system rules are defined in `app/CLAUDE.md` under **"FRONTEND RULES"**. Read that section before writing any UI. The `StatisticsCard` component at `@/components/statistics-card` is the only allowed stat card implementation — do not write inline stat card markup.

---

## Critical Rules

| Rule | Detail |
|------|--------|
| DB connection | Always `central` — models use `protected $connection = 'central'` |
| Guard | `admin` — never `web` (that's tenant) |
| Auth model | `Admin` — not `User` (User is tenant-scoped) |
| Migrations | Go in `database/migrations/` here — NOT in `app/database/migrations/tenant/` |
| New admin features | Add controller under `app/Http/Controllers/Admin/`, register in `routes/admin.php` |

---

## Directory Structure

```
AdminApp/
├── app/
│   ├── Http/Controllers/
│   │   ├── Admin/              ← Super Admin features (tenant mgmt, packages, features)
│   │   │   ├── TenantController.php
│   │   │   ├── PackageController.php
│   │   │   ├── FeatureController.php
│   │   │   ├── AppManagementController.php
│   │   │   └── AdminController.php / AdminRoleController.php
│   │   └── Settings/           ← Platform settings (email, theme, general)
│   ├── Models/                 ← All use central connection
│   │   ├── Admin.php           ← Platform super admin user
│   │   ├── AdminRole.php / AdminPermission.php
│   │   ├── Tenant.php          ← Stancl tenant (central)
│   │   ├── FeatureManagement.php
│   │   ├── ModuleManagement.php
│   │   ├── Package.php / Subscription.php
│   │   └── Domain.php / DomainSslConfig.php
│   ├── DTO/                    ← Use these — AdminDTO, TenantDTO, PackageDTO, etc.
│   ├── Enums/                  ← PackageTypeEnum, SubscriptionTypeEnum, BillingCycleEnum
│   └── Services/               ← Business logic (CONSTITUTION.md rules apply here too)
├── database/
│   ├── migrations/             ← Central DB migrations ONLY
│   └── seeders/
│       ├── FeatureManagement/  ← One file per app (CrmApp.php, EcommerceApp.php, etc.)
│       │   └── Contracts/AbstractAppDefinition.php  ← Extend this for new apps
│       └── PackageManagement/  ← Startup/Professional/Enterprise packages
│           └── Contracts/AbstractPackageDefinition.php
└── routes/
    ├── admin.php               ← /admin/* routes (guard: admin)
    ├── web.php                 ← / routes (public/auth pages)
    └── auth.php                ← Login/logout/password reset
```

---

## Adding New Super Admin Features (e.g. Garment ERP phase config)

1. Create controller: `app/Http/Controllers/Admin/GarmentTenantController.php`
2. Create migration: `database/migrations/YYYY_MM_DD_create_tenant_phase_configs_table.php`
3. Register route in `routes/admin.php` under `auth:admin` middleware
4. Add DTO in `app/DTO/` if needed
5. Add feature seeder in `database/seeders/FeatureManagement/GarmentApp.php` extending `AbstractAppDefinition`

---

## FeatureManagement Seeder Pattern

To register a new app's features (so they appear in package management):

```php
// database/seeders/FeatureManagement/GarmentApp.php
class GarmentApp extends AbstractAppDefinition
{
    // Define app name, modules, and features
    // See CrmApp.php or ProductivityApp.php for reference
}
```

Register it in `AdminDatabaseSeeder.php`.

---

## Key Relationships

```
Package → PackageApp → PackageModule → PackageFeature
Tenant → Subscription → Package
Admin → AdminRole → AdminPermission
FeatureManagement → ModuleManagement → AppManagement
```

---

## Product Profile System (IMPORTANT — read after any reseed)

After running `dev:install` or any seeder reset, `taskco-erp` is **applied automatically** (it is the default). To switch to a different product:

```bash
php artisan profile:apply taskco-ecommerce   # or taskco-sales / taskco-education
php artisan profile:apply --list             # see all profiles + which is active
```

Or via Admin UI: **Workspace Settings → Product Profiles → Apply**

Available profiles: `taskco-erp` (default), `taskco-ecommerce`, `taskco-sales`, `taskco-education`.

Profile config files live in `config/product-profiles/*.php` — version-controlled, never lost.
Module registry: `config/modules.json` — full list of all app slugs and module slugs.
Full documentation: [`docs/PRODUCT-PROFILES.md`](docs/PRODUCT-PROFILES.md)

**Seeder rule:** Use `firstOrCreate` (not `updateOrCreate`) for any setting the admin controls
(branding, app_name, personalizer rows). Only structural/email settings should use `updateOrCreate`.