How nazim1971/dark-pb works
1. This repository is a NestJS 10 TypeScript backend for a Music Publishing Administration Portal. Its core infrastructure is PostgreSQL accessed through Prisma, with the schema and seed flow living under prisma/.
2. The application is organized as a module-per-domain backend. src/app.module.ts composes feature modules, and most business areas follow the same shape: controller, service, DTOs, and Zod schemas. That makes the module boundary the main architectural unit, not a monolithic service layer.
3. The request pipeline is heavily standardized in main.ts and shared utilities: global validation, Zod-based request/response validation, global response shaping, exception filtering, logging middleware, and throttling. Swagger is wired through src/common/utils/swagger.ts and exposed at /docs.
4. Authentication is a dedicated subsystem under src/auth/. It uses JWT access tokens with a refresh flow, a JWT strategy, auth and roles guards, and decorators for public routes, current user extraction, and role checks. Authorization is role-based, with ADMIN gating the privileged endpoints.
5. Persistence is abstracted through src/prisma/, which provides PrismaService, a base repository, and query helpers. Domain services depend on this layer to read/write the canonical data model defined in prisma/schema.prisma. The seed script initializes bootstrap data, including admin credentials from environment variables.
6. The main business data flows center on music publishing entities: compositions, writers, publishers, recordings, contracts, royalties, statements, and conflicts. Compositions appear to be the hub, with related relations updated separately, then reused downstream for contracts, royalty accounting, statement generation, and conflict resolution.
7. Operational workflows are split into separate modules:
• compositions handles creation, submission, approval, rejection, and relation management.
• contracts manages contract lifecycle and composition attachment.
• royalties records royalty entries, analytics, and exports.
• statements generates statement artifacts and exports.
• conflicts detects, reviews, and resolves claim disputes.
• support manages user ticketing, replies, and ticket status history.
8. The admin subsystem is its own boundary under src/admin/. It handles KYC approval/rejection, work approval/rejection, metadata correction, ISWC/IPI updates, dashboard reporting, activity reporting, and admin export formats. This module is also where audit-style actions are surfaced.
9. Reporting and export are first-class concerns rather than an afterthought. src/reports/ and the export helpers in src/reports/export.utils.ts and src/admin/admin-export.utils.ts support CSV, Excel, PDF, and CWR outputs. These exports are generated from persisted domain data and are used by royalties, statements, reports, and admin reporting endpoints.
10. Search is isolated in src/search/ and acts as a read-optimized query surface across multiple domains. It can query compositions, writers, publishers, artists, and identifier fields like ISRC, ISWC, and IPI, which makes it a cross-cutting retrieval layer rather than a transactional workflow.
11. src/common/ and src/shared/ hold the cross-cutting building blocks: pagination contracts, sort enums, API response interfaces, config validation, Swagger helpers, error formatting, and Zod validation primitives. These packages are what keep the feature modules consistent without coupling them together.
12. There are also scaffolded modules for kyc, notifications, publishers, recordings, and writers. Their controllers exist, but they appear to be placeholders compared with the fully implemented domains, so in an architecture diagram they should be shown as planned or partial subsystems rather than active workflow centers.
Main entry points: app.module.ts App module · prisma.module.ts Prisma · reports.module.ts Reports · admin.module.ts Admin
Components 23
Runtime
Application bootstrap and request pipeline
- main.ts · Nest entrypoint and global pipeline setup
src/main.ts - App module · Composes feature modules
src/app.module.ts
Cross-cutting
Shared validation, auth, persistence, and tooling
- Auth · Login, refresh, guards, roles, and current-user decorators
src/auth/auth.module.ts - Prisma · Prisma service, repository base, and query helpers
src/prisma/prisma.module.ts - Common · Validation, response shaping, exceptions, logging, and Swagger helpers
src/common/utils/swagger.ts - Shared · Pagination, sort enums, and API contracts used across modules
src/shared/interfaces/pagination.interface.ts
Core domains
Implemented business workflows and read surfaces
- Compositions · Composition creation, submission, approval, and relation management
src/compositions/compositions.module.ts - Contracts · Contract lifecycle and composition attachment
src/contracts/contracts.module.ts - Royalties · Royalty entries, analytics, and exports
src/royalties/royalties.module.ts - Statements · Statement generation and file/export handling
src/statements/statements.module.ts - Conflicts · Claim detection, review, and resolution
src/conflicts/conflicts.module.ts - Admin · KYC/work approval, metadata correction, reporting, and admin exports
src/admin/admin.module.ts - Reports · Report endpoints and export format generation
src/reports/reports.module.ts - Search · Cross-domain lookup for compositions and identifiers
src/search/search.module.ts - Support · Tickets, replies, and status history
src/support/support.module.ts - Users · User-facing account module
src/users/users.module.ts
Partial modules
Present but comparatively lightweight subsystems
- Publishers · Scaffolded publisher boundary
src/publishers/publishers.module.ts - Recordings · Scaffolded recording boundary
src/recordings/recordings.module.ts - Writers · Scaffolded writer boundary
src/writers/writers.module.ts - Notifications · Scaffolded notification boundary
src/notifications/notifications.module.ts - KYC · Scaffolded KYC boundary
src/kyc/kyc.module.ts
Data model
Prisma schema and seed bootstrap
- Prisma schema · Canonical PostgreSQL schema definition
prisma/schema.prisma - Seed · Database seed and admin bootstrap
prisma/seed.ts
Connections 31
- main.ts → App module: boots · Application entrypoint loads the composition root
- main.ts → Common: installs · Global validation, filters, interceptors, middleware, and docs
- main.ts → Auth: configures · JWT auth pipeline and request context
- App module → Auth: imports · Authentication subsystem is part of the root module
- App module → Prisma: imports · Shared persistence layer is available to feature modules
- App module → Compositions: composes · Core composition workflow is wired into the app
- App module → Contracts: composes · Contract workflow is wired into the app
- App module → Royalties: composes · Royalty accounting workflow is wired into the app
- App module → Statements: composes · Statement workflow is wired into the app
- App module → Conflicts: composes · Conflict workflow is wired into the app
- App module → Admin: composes · Admin moderation subsystem is wired into the app
- App module → Reports: composes · Reporting subsystem is wired into the app
- App module → Search: composes · Search surface is wired into the app
- App module → Support: composes · Support ticketing module is wired into the app
- App module → Users: composes · User management module is wired into the app
- Compositions → Prisma: reads/writes · Composition lifecycle persists through Prisma repositories
- Contracts → Prisma: reads/writes · Contract attachments and state changes persist through Prisma
- Royalties → Prisma: reads/writes · Royalty records and exports come from persisted data
- Statements → Prisma: reads/writes · Statements are generated from persisted financial data
- Conflicts → Prisma: reads/writes · Conflict review and resolution operate on stored claims
- Admin → Prisma: reads/writes · Admin approvals and corrections update canonical records
- Reports → Prisma: reads · Reporting aggregates persisted domain data
- Search → Prisma: reads · Read-optimized search queries the canonical store
- Support → Prisma: reads/writes · Tickets and reply history persist in the database
- Users → Prisma: reads/writes · User account data is persisted through Prisma
- Admin → Reports: uses · Admin dashboards and exports reuse reporting capabilities
- Admin → Common: uses · Shares validation, response, and error handling primitives
- Compositions → Search: feeds · Composition data becomes searchable across domains
- Royalties → Reports: exports · Royalty outputs use shared export formats
- Statements → Reports: exports · Statement files rely on report/export utilities
- Prisma schema → Seed: initializes · Seed data targets the canonical Prisma schema