# nazim1971/dark-pb architecture

> Architecture diagram of the GitHub repository nazim1971/dark-pb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nazim1971/dark-pb
- Repository: https://github.com/nazim1971/dark-pb

## Overview

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: [`src/app.module.ts`](https://github.com/nazim1971/dark-pb/blob/main/src/app.module.ts) (App module), [`src/prisma/prisma.module.ts`](https://github.com/nazim1971/dark-pb/blob/main/src/prisma/prisma.module.ts) (Prisma), [`src/reports/reports.module.ts`](https://github.com/nazim1971/dark-pb/blob/main/src/reports/reports.module.ts) (Reports), [`src/admin/admin.module.ts`](https://github.com/nazim1971/dark-pb/blob/main/src/admin/admin.module.ts) (Admin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["main.ts<br/>bootstrap<br/>[main.ts]"]
  node_app["App module<br/>composition root<br/>[app.module.ts]"]
end

subgraph group_crosscutting["Cross-cutting"]
  node_auth["Auth<br/>[auth.module.ts]"]
  node_prisma[("Prisma<br/>data access<br/>[prisma.module.ts]")]
  node_common["Common<br/>shared infra<br/>[swagger.ts]"]
  node_shared["Shared<br/>contracts"]
end

subgraph group_domains["Core domains"]
  node_compositions["Compositions<br/>catalog workflow"]
  node_contracts["Contracts<br/>agreement workflow"]
  node_royalties["Royalties<br/>accounting"]
  node_statements["Statements<br/>reporting"]
  node_conflicts["Conflicts<br/>dispute workflow"]
  node_admin["Admin<br/>moderation<br/>[admin.module.ts]"]
  node_reports["Reports<br/>export hub<br/>[reports.module.ts]"]
  node_search["Search<br/>read surface<br/>[search.module.ts]"]
  node_support["Support<br/>ticketing<br/>[support.module.ts]"]
  node_users["Users<br/>account domain<br/>[users.module.ts]"]
end

subgraph group_scaffold["Partial modules"]
  node_publishers["Publishers<br/>partial domain"]
  node_recordings["Recordings<br/>partial domain"]
  node_writers["Writers<br/>partial domain<br/>[writers.module.ts]"]
  node_notifications["Notifications<br/>partial domain"]
  node_kyc["KYC<br/>partial domain<br/>[kyc.module.ts]"]
end

subgraph group_data["Data model"]
  node_schema["Prisma schema<br/>data model<br/>[schema.prisma]"]
  node_seed["Seed<br/>bootstrap data<br/>[seed.ts]"]
end

node_main -->|"boots"| node_app
node_main -->|"installs"| node_common
node_main -->|"configures"| node_auth
node_app -->|"imports"| node_auth
node_app -->|"imports"| node_prisma
node_app -->|"composes"| node_compositions
node_app -->|"composes"| node_contracts
node_app -->|"composes"| node_royalties
node_app -->|"composes"| node_statements
node_app -->|"composes"| node_conflicts
node_app -->|"composes"| node_admin
node_app -->|"composes"| node_reports
node_app -->|"composes"| node_search
node_app -->|"composes"| node_support
node_app -->|"composes"| node_users
node_compositions -->|"reads/writes"| node_prisma
node_contracts -->|"reads/writes"| node_prisma
node_royalties -->|"reads/writes"| node_prisma
node_statements -->|"reads/writes"| node_prisma
node_conflicts -->|"reads/writes"| node_prisma
node_admin -->|"reads/writes"| node_prisma
node_reports -->|"reads"| node_prisma
node_search -->|"reads"| node_prisma
node_support -->|"reads/writes"| node_prisma
node_users -->|"reads/writes"| node_prisma
node_admin -->|"uses"| node_reports
node_admin -->|"uses"| node_common
node_compositions -->|"feeds"| node_search
node_royalties -->|"exports"| node_reports
node_statements -->|"exports"| node_reports
node_schema -->|"initializes"| node_seed

click node_main "https://github.com/nazim1971/dark-pb/blob/main/src/main.ts"
click node_app "https://github.com/nazim1971/dark-pb/blob/main/src/app.module.ts"
click node_auth "https://github.com/nazim1971/dark-pb/blob/main/src/auth/auth.module.ts"
click node_prisma "https://github.com/nazim1971/dark-pb/blob/main/src/prisma/prisma.module.ts"
click node_common "https://github.com/nazim1971/dark-pb/blob/main/src/common/utils/swagger.ts"
click node_shared "https://github.com/nazim1971/dark-pb/blob/main/src/shared/interfaces/pagination.interface.ts"
click node_compositions "https://github.com/nazim1971/dark-pb/blob/main/src/compositions/compositions.module.ts"
click node_contracts "https://github.com/nazim1971/dark-pb/blob/main/src/contracts/contracts.module.ts"
click node_royalties "https://github.com/nazim1971/dark-pb/blob/main/src/royalties/royalties.module.ts"
click node_statements "https://github.com/nazim1971/dark-pb/blob/main/src/statements/statements.module.ts"
click node_conflicts "https://github.com/nazim1971/dark-pb/blob/main/src/conflicts/conflicts.module.ts"
click node_admin "https://github.com/nazim1971/dark-pb/blob/main/src/admin/admin.module.ts"
click node_reports "https://github.com/nazim1971/dark-pb/blob/main/src/reports/reports.module.ts"
click node_search "https://github.com/nazim1971/dark-pb/blob/main/src/search/search.module.ts"
click node_support "https://github.com/nazim1971/dark-pb/blob/main/src/support/support.module.ts"
click node_users "https://github.com/nazim1971/dark-pb/blob/main/src/users/users.module.ts"
click node_publishers "https://github.com/nazim1971/dark-pb/blob/main/src/publishers/publishers.module.ts"
click node_recordings "https://github.com/nazim1971/dark-pb/blob/main/src/recordings/recordings.module.ts"
click node_writers "https://github.com/nazim1971/dark-pb/blob/main/src/writers/writers.module.ts"
click node_notifications "https://github.com/nazim1971/dark-pb/blob/main/src/notifications/notifications.module.ts"
click node_kyc "https://github.com/nazim1971/dark-pb/blob/main/src/kyc/kyc.module.ts"
click node_schema "https://github.com/nazim1971/dark-pb/blob/main/prisma/schema.prisma"
click node_seed "https://github.com/nazim1971/dark-pb/blob/main/prisma/seed.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app toneBlue
class node_auth,node_prisma,node_common,node_shared toneAmber
class node_compositions,node_contracts,node_royalties,node_statements,node_conflicts,node_admin,node_reports,node_search,node_support,node_users toneMint
class node_publishers,node_recordings,node_writers,node_notifications,node_kyc toneRose
class node_schema,node_seed toneIndigo
```

## Components

### Runtime

Application bootstrap and request pipeline

- [main.ts](https://github.com/nazim1971/dark-pb/blob/main/src/main.ts): bootstrap · Nest entrypoint and global pipeline setup · `src/main.ts`
- [App module](https://github.com/nazim1971/dark-pb/blob/main/src/app.module.ts): composition root · Composes feature modules · `src/app.module.ts`

### Cross-cutting

Shared validation, auth, persistence, and tooling

- [Auth](https://github.com/nazim1971/dark-pb/blob/main/src/auth/auth.module.ts): JWT auth · Login, refresh, guards, roles, and current-user decorators · `src/auth/auth.module.ts`
- [Prisma](https://github.com/nazim1971/dark-pb/blob/main/src/prisma/prisma.module.ts): data access · Prisma service, repository base, and query helpers · `src/prisma/prisma.module.ts`
- [Common](https://github.com/nazim1971/dark-pb/blob/main/src/common/utils/swagger.ts): shared infra · Validation, response shaping, exceptions, logging, and Swagger helpers · `src/common/utils/swagger.ts`
- [Shared](https://github.com/nazim1971/dark-pb/blob/main/src/shared/interfaces/pagination.interface.ts): contracts · Pagination, sort enums, and API contracts used across modules · `src/shared/interfaces/pagination.interface.ts`

### Core domains

Implemented business workflows and read surfaces

- [Compositions](https://github.com/nazim1971/dark-pb/blob/main/src/compositions/compositions.module.ts): catalog workflow · Composition creation, submission, approval, and relation management · `src/compositions/compositions.module.ts`
- [Contracts](https://github.com/nazim1971/dark-pb/blob/main/src/contracts/contracts.module.ts): agreement workflow · Contract lifecycle and composition attachment · `src/contracts/contracts.module.ts`
- [Royalties](https://github.com/nazim1971/dark-pb/blob/main/src/royalties/royalties.module.ts): accounting · Royalty entries, analytics, and exports · `src/royalties/royalties.module.ts`
- [Statements](https://github.com/nazim1971/dark-pb/blob/main/src/statements/statements.module.ts): reporting · Statement generation and file/export handling · `src/statements/statements.module.ts`
- [Conflicts](https://github.com/nazim1971/dark-pb/blob/main/src/conflicts/conflicts.module.ts): dispute workflow · Claim detection, review, and resolution · `src/conflicts/conflicts.module.ts`
- [Admin](https://github.com/nazim1971/dark-pb/blob/main/src/admin/admin.module.ts): moderation · KYC/work approval, metadata correction, reporting, and admin exports · `src/admin/admin.module.ts`
- [Reports](https://github.com/nazim1971/dark-pb/blob/main/src/reports/reports.module.ts): export hub · Report endpoints and export format generation · `src/reports/reports.module.ts`
- [Search](https://github.com/nazim1971/dark-pb/blob/main/src/search/search.module.ts): read surface · Cross-domain lookup for compositions and identifiers · `src/search/search.module.ts`
- [Support](https://github.com/nazim1971/dark-pb/blob/main/src/support/support.module.ts): ticketing · Tickets, replies, and status history · `src/support/support.module.ts`
- [Users](https://github.com/nazim1971/dark-pb/blob/main/src/users/users.module.ts): account domain · User-facing account module · `src/users/users.module.ts`

### Partial modules

Present but comparatively lightweight subsystems

- [Publishers](https://github.com/nazim1971/dark-pb/blob/main/src/publishers/publishers.module.ts): partial domain · Scaffolded publisher boundary · `src/publishers/publishers.module.ts`
- [Recordings](https://github.com/nazim1971/dark-pb/blob/main/src/recordings/recordings.module.ts): partial domain · Scaffolded recording boundary · `src/recordings/recordings.module.ts`
- [Writers](https://github.com/nazim1971/dark-pb/blob/main/src/writers/writers.module.ts): partial domain · Scaffolded writer boundary · `src/writers/writers.module.ts`
- [Notifications](https://github.com/nazim1971/dark-pb/blob/main/src/notifications/notifications.module.ts): partial domain · Scaffolded notification boundary · `src/notifications/notifications.module.ts`
- [KYC](https://github.com/nazim1971/dark-pb/blob/main/src/kyc/kyc.module.ts): partial domain · Scaffolded KYC boundary · `src/kyc/kyc.module.ts`

### Data model

Prisma schema and seed bootstrap

- [Prisma schema](https://github.com/nazim1971/dark-pb/blob/main/prisma/schema.prisma): data model · Canonical PostgreSQL schema definition · `prisma/schema.prisma`
- [Seed](https://github.com/nazim1971/dark-pb/blob/main/prisma/seed.ts): bootstrap data · Database seed and admin bootstrap · `prisma/seed.ts`

## Connections

- 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
