# Tenancy Management

Platform, merchant, store, and admin user management. Required for multi-tenant operation.

## Overview

| Aspect | Detail |
|--------|--------|
| Code | `tenancy` |
| Classification | Core |
| Dependencies | None |
| Status | Active |

## Features

- `platform_management` — Platform-level administration
- `merchant_management` — Merchant account management
- `store_management` — Store configuration and setup
- `admin_user_management` — Admin user accounts and team management

## Permissions

| Permission | Description |
|------------|-------------|
| `team.view` | View team members |
| `team.invite` | Invite team members (owner only) |
| `team.edit` | Edit team members (owner only) |
| `team.remove` | Remove team members (owner only) |

## Data Model

See [Data Model](data-model.md) for full entity relationships.

- **Platform** — Top-level SaaS instances
- **Merchant** — Business entities that own stores
- **Store** — Storefronts with multi-tenant scoping
- **User** — Admin users (super_admin, platform_admin, merchant_owner, store_member)
- **StoreUser** — Store membership with role assignment
- **Role** — Permission roles for team members
- **StoreDomain / MerchantDomain** — Custom domain configuration
- **EmailVerificationToken** — Email verification tokens

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `*` | `/api/v1/admin/auth/*` | Authentication (login, register, password reset) |
| `*` | `/api/v1/admin/merchants/*` | Merchant CRUD |
| `*` | `/api/v1/admin/modules/*` | Module enable/disable |
| `*` | `/api/v1/admin/merchant-domains/*` | Domain management |
| `*` | `/api/v1/admin/store-roles/*` | Admin role management |
| `*` | `/api/v1/store/team/*` | Team & role management |
| `*` | `/api/v1/store/onboarding/*` | Store onboarding wizard |

## Configuration

No module-specific configuration.

## Additional Documentation

- [Data Model](data-model.md) — Entity relationships and database schema
- [RBAC System](rbac.md) — Role-based access control, permissions, pre-defined roles
- [Store Onboarding](onboarding.md) — 4-step onboarding wizard
- [Migration Plan](migration.md) — Code migration plan from legacy structure
