From d3a8eab11844d1af5c6e5f537401cf3fd7f00754 Mon Sep 17 00:00:00 2001 From: Rayyan <60314224+RayyanHermanto@users.noreply.github.com> Date: Mon, 3 Aug 2026 00:53:18 +0700 Subject: [PATCH] Delete PHASE1_README.md --- PHASE1_README.md | 165 ----------------------------------------------- 1 file changed, 165 deletions(-) delete mode 100644 PHASE1_README.md diff --git a/PHASE1_README.md b/PHASE1_README.md deleted file mode 100644 index 4a6aefd..0000000 --- a/PHASE1_README.md +++ /dev/null @@ -1,165 +0,0 @@ -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. -