Phase 1 Deliverables - RayLab Core
=================================

Contents
--------
1. Architecture explanation
2. Folder structure
3. Source code references (what was added/changed)
4. Database schema (Prisma)
5. Migration (SQL)
6. Seed data (script)
7. API design (initial endpoints)
8. Design decisions
9. Advantages
10. Possible future extensions
11. How to run (migrate & seed)

1) Architecture explanation
--------------------------
Phase 1 establishes the foundational data model and project layout for RayLab Core. It prepares the system for secure integration with Authentik (OIDC) and supports role/permission based authorization owned by RayLab Core. The design follows Clean Architecture, SOLID principles, modular NestJS structure, and Prisma for type-safe DB access.

Key principles applied:
- RayLab Core does NOT implement authentication; it only validates external OIDC tokens (Phase 2).
- Roles, permissions, role mappings, users, and audit logs are owned by RayLab Core. Media Manager and Scheduler are intentionally excluded from Phase 1 and will be implemented in Phase 3.
- No Group entity is created in RayLab Core; only mapping configuration (auth group name string -> role) is stored.
- Critical operations (synchronization) will be transactional (Phase 2 implementation).

2) Folder structure
-------------------
(Only top-level relevant directories shown)

- prisma/
  - schema.prisma                // Prisma schema (source of truth for DB)
  - migrations/0001_init/        // Initial SQL migration
  - seed.ts                      // Seed script (idempotent upserts)

- src/
  - main.ts
  - app.module.ts
  - modules/
    - identity/                   // DDD-based users/roles/permissions implementation
    - auth/                       // (Phase 2) OIDC integration
    - authorization/              // (Phase 2) permission guards & services
    - health/                     // basic health endpoint (added)
    - media/                      // media manager module (phase 3)
    - audit/                      // audit module (phase 3)
    - ... other domain modules
  - shared/
    - prisma.service.ts
    - ...

3) Source code (what was added/changed)
---------------------------------------
- prisma/schema.prisma (UPDATED): replaced with production-ready schema containing:
  User, Role, Permission, RolePermission, UserRole, AuthGroupRoleMapping, AuditLog

- prisma/migrations/0001_init/migration.sql (ADDED): initial SQL migration DDL

- prisma/seed.ts (UPDATED): seed script that creates default roles, permissions, role-permission assignments, and Authentik group -> role mappings

- src/modules/health/* (ADDED): HealthModule, Controller, Service (thin controller)

- src/shared/prisma.service.ts (EXISTING): PrismaService (already present)

4) Database schema
------------------
The Prisma schema (prisma/schema.prisma) is the authoritative schema. High-level model summary:
- User: id (uuid), externalId (unique), email, name, picture, metadata, createdAt, updatedAt
- Role: id, name (unique), displayName, description
- Permission: id, name (unique), description
- RolePermission: join table role <-> permission (unique constraint roleId+permissionId)
- UserRole: join table user <-> role with source (e.g., 'authentik') and syncedAt timestamp (unique userId+roleId)
- AuthGroupRoleMapping: mapping table authGroup (string) -> roleId. One authGroup may map to multiple roles (no uniqueness enforced on authGroup).
- AuditLog: append-only audit logs with JSON details


Indexes and constraints are included for common lookup paths. The migration SQL contains explicit DDL statements.

5) Migration
------------
- prisma/migrations/0001_init/migration.sql contains the SQL to create the schema.
- The migration file includes CREATE EXTENSION IF NOT EXISTS "pgcrypto" to provide gen_random_uuid().
- Recommended migration procedure in production:
  1. Ensure backups and schedule maintenance window for initial deployment.
  2. Run migrations with Prisma or psql: "psql < migration.sql" or use "prisma migrate deploy" after generating migrations from schema.prisma.

6) Seed data
------------
- prisma/seed.ts seeds the following:
  - Default roles: Owner, Employee, Family
  - Default permissions following resource.action naming convention (users.create, users.read, ..., scheduler.manage)
  - RolePermission assignments:
    - Owner receives all permissions
    - Employee and Family receive reasonable subsets (editable later)
  - Authentik group mappings:
    - RL-Owner -> Owner
    - RL-Employee -> Employee
    - RL-Family -> Family

The seed script is idempotent using upsert operations.

7) API design (initial)
-----------------------
Phase 1 provides a minimal, safe public surface to verify system health and readiness.
- GET /api/health
  - Returns: { status: 'ok', timestamp, service }

Identity module controllers (users, roles, permissions) are present under src/modules/identity/presentation/controllers and follow RESTful conventions, but full auth/guards are implemented in Phase 2.

8) Design decisions
-------------------
- Prisma selected for type-safe DB access and migrations. (User requested Prisma)
- UUID primary keys (Postgres gen_random_uuid()) for scalability and horizontal distribution.
- JSONB (Prisma Json) used for flexible metadata and audit details.
- AuthGroupRoleMapping stores external group string only; RayLab Core does NOT model Groups as domain entities.
- Seed sets conservative permission assignments; owners get full permissions.
- Minimal initial API surface (health) avoids unintentionally exposing functionality before auth & guards are in place.

9) Advantages
-------------
- Production-ready DB schema with indices and constraints for performance and data integrity.
- Modular NestJS structure aligned with Clean Architecture / DDD; easy to extend in subsequent phases.
- Prisma provides type-safety and reduces runtime errors.
- Seed script allows reproducible environments and CI setup.
- Audit and media tables are present to support required domain features.

10) Possible future extensions
------------------------------
Planned for Phase 2 and 3 (once Phase 1 is approved):
- OIDC validation using openid-client and configuration from env vars
- Role synchronization flow (validate token -> read groups -> map -> compute hash -> replace UserRole in transaction -> invalidate permission cache -> write audit)
- Permission cache using Redis, invalidation hooks
- Auth guards and AuthorizationService for permission checks
- Media Manager: presigned URLs, storage backend (S3/MinIO)
- Scheduler: BullMQ integration with Redis
- Monitoring: Prometheus metrics, structured logging, Sentry

11) How to run (migrate & seed)
-------------------------------
Prerequisites:
- Node 20+
- PostgreSQL reachable via DATABASE_URL env var
- Install dependencies: npm ci

Generate Prisma client and run migration:

1) Generate Prisma client:
   npm run prisma:generate

2) Apply migration (development):
   npm run prisma:migrate

   Or run SQL directly against the database:
   psql "$DATABASE_URL" -f prisma/migrations/0001_init/migration.sql

3) Run seed script:
   npm run prisma:seed

4) Start the app (development):
   npm run start:dev

Next steps
----------
Please review Phase 1 deliverables. After your approval I will implement Phase 2 (OIDC module, Authentik integration, Group->Role Sync, Authorization Guard, Permission Cache, Audit logging) following the same level of production-quality implementation.