Phase 3 Completed
This commit is contained in:
Rayyan
@@ -0,0 +1,165 @@
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user