166 lines
7.3 KiB
Markdown
166 lines
7.3 KiB
Markdown
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.
|
|
|