NestJS drop-in replacement for tc-project-service, serving the Topcoder platform at /v6/projects.

• Overview
• Architecture
• API Reference
• Platform Consumers
• Authorization Model
• Event Publishing
• Environment Variables
• Setup and Development
• Testing
• Deployment
• Security Notes
• Dependency Status
• Code Quality Notes
• Migration from v5
• Related Documentation

Projects API v6 manages the full project lifecycle: project CRUD, member management, invites, phases, phase products, attachments, workstreams, copilot request/opportunity/application workflows, and metadata.

It is the platform replacement for tc-project-service (/v5) and is consumed by multiple frontend apps and backend services.

Key design decisions:

• Elasticsearch removed; Prisma + PostgreSQL handle all reads and writes.
• NestJS modular architecture with focused feature modules.
• Layered JWT + M2M authorization.
• Kafka event publishing for mutation flows.

sequenceDiagram
    participant Client
    participant TokenRolesGuard
    participant ProjectContextInterceptor
    participant PermissionGuard
    participant Controller
    participant Service
    participant Prisma
    participant EventBus

    Client->>TokenRolesGuard: HTTP request + Bearer JWT / M2M token
    TokenRolesGuard->>TokenRolesGuard: Validate JWT, set request.user
    TokenRolesGuard->>ProjectContextInterceptor: pass
    ProjectContextInterceptor->>Prisma: Load project members (if :projectId route)
    ProjectContextInterceptor->>Controller: request.projectContext populated
    Controller->>PermissionGuard: @RequirePermission check
    PermissionGuard->>Controller: authorized
    Controller->>Service: business logic
    Service->>Prisma: DB query
    Service->>EventBus: publish Kafka event (on mutations)
    Service-->>Controller: result
    Controller-->>Client: HTTP response

For the full v5 -> v6 mapping table, see docs/api-usage-analysis.md.

Talent Manager note:

• Talent Manager and Topcoder Talent Manager callers create projects as primary manager members.
• Talent Manager and Topcoder Talent Manager users can also be assigned the manager (Full Access) project role through member add/update/invite flows.
• Talent Manager and Topcoder Talent Manager callers also receive the elevated per-member response from GET /v6/projects/:projectId/permissions, which is used to provision challenge-related actions in Work Manager.
• Updating billingAccountId is restricted to human administrators and project members whose role on that project is manager (Full Access).

Copilot request management routes accept M2M tokens with project-write authorization such as write:projects, all:projects, or all:connect_project.

The opportunity list supports database-level search, status, projectId, projectName, type, skills, requested-start/created date ranges, sorting, and current-user applied / applicationStatus filters. The existing response array and pagination headers remain compatible. See docs/copilot-opportunities.md for the exact contract, aliases, current-user fields, and examples.

Cross-service consumers can install the checked-in packages/projects-prisma-client subdirectory as @topcoder/projects-api-v6. It exports all generated Projects Prisma models, enums, and PrismaClient, plus createProjectsPrismaClient(connectionString, options?), which configures the required Prisma 7 PostgreSQL adapter. See the package README for installation and lifecycle usage.

See docs/api-usage-analysis.md (P2 section) for the complete metadata list.

Swagger UI: http://localhost:3000/v6/projects/api-docs

• PROJECTS_API_URL resolves to ${EnvironmentConfig.API.V6}/projects.
• Calls GET /v6/projects (paginated listing with sort, status, memberOnly, billingAccountId, keyword), GET /v6/projects/:id, POST /v6/projects, PATCH /v6/projects/:id.
• Member operations: POST /members, PATCH /members/:id, DELETE /members/:id.
• Invite operations via platform-ui/src/apps/work/src/lib/services/project-member-invites.service.ts: POST /invites?fields=..., PATCH /invites/:id, DELETE /invites/:id.
• Phase/product linkage: GET /phases?fields=id,name,products,status, POST /phases/:phaseId/products (challenge linkage with details.challengeGuid), DELETE /phases/:phaseId/products/:productId.
• Attachment operations: GET /attachments/:id, POST /attachments, PATCH /attachments/:id, DELETE /attachments/:id.
• Billing: GET /billingAccount.
• Metadata: GET /metadata/projectTypes with fallback to GET /metadata.

• baseUrl resolves to ${EnvironmentConfig.API.V6}/projects.
• Uses SWR hook useProjects for reactive project listing with chunked ID filtering (20 IDs per request, 200 ms rate-limit delay between chunks).
• Calls GET /v6/projects (with name search and arbitrary filter params), GET /v6/projects/:id.

• Heaviest consumer of the P0 surface: project CRUD/listing, billing lookups, member/invite write flows, attachment file/link flows, phase-product linkage.
• Uses action: "complete-copilot-requests" on PATCH /members/:id to trigger copilot workflow side effects.
• Reads pagination headers: X-Page, X-Per-Page, X-Total, X-Total-Pages.

• Calls GET /v6/projects/:projectId to validate project existence and extract members[] + invites[] for engagement creation.

• Calls GET /v6/projects/:projectId and GET /v6/projects/:projectId/billingAccount (reads markup field for M2M payment flows).
• Calls POST /v6/projects and PATCH /v6/projects/:projectId for self-service challenge project lifecycle.

• Calls GET /v6/projects/copilots/opportunities?noGrouping=true (public endpoint) for the copilot marketplace listing.

Layered auth details and guard usage are documented in docs/PERMISSIONS.md.

JWT Bearer token -> TokenRolesGuard -> request.user
                                          ↓
                    ProjectContextInterceptor (loads project members for :projectId routes)
                                          ↓
                    PermissionGuard / AdminOnlyGuard / ProjectMemberGuard / CopilotAndAboveGuard
                                          ↓
                    Controller (@CurrentUser, @ProjectMembers decorators)

• TokenRolesGuard validates JWT or M2M token; routes decorated with @Public() bypass it.
• PermissionGuard evaluates @RequirePermission(PERMISSION.X) using allow + deny rule semantics.
• AdminOnlyGuard restricts to Topcoder admin roles.
• ProjectMemberGuard requires caller to be a project member; optionally filtered by @RequireProjectMemberRoles(...).
• CopilotAndAboveGuard requires copilot, manager, or admin role.

For full event envelope and payload schemas, see docs/event-schemas.md.

• Originator: project-service-v6.
• Status-change events are emitted only when status actually changes.
• Billing-account update event payload matches legacy tc-project-service contract and is sent as raw payload (no resource/data wrapper).
• Metadata event publishing is currently disabled.

Reference source: .env.example.

• Node.js v26.5.1 (nvm use in this project folder)
• pnpm 10.28.2
• PostgreSQL

pnpm install

postinstall runs prisma generate.

Configure DATABASE_URL, then run:

pnpm exec prisma migrate dev
pnpm prisma db seed

Copy .env.example to .env and fill in all required variables.

pnpm run start:dev

pnpm run build
pnpm run start:prod

pnpm lint

Must pass before every commit per AGENTS.md.

pnpm build

Must pass before every commit per AGENTS.md.

• CI/CD: CircleCI -> AWS ECS Fargate.
• The multi-stage Docker image builds with Node 26.5.1 and copies only compiled output, production dependencies, and Prisma migration assets into its Alpine 3.24 runtime. The runtime installs the dynamically linked Alpine Node package and does not contain npm or other package tooling.
• Container startup invokes the local Prisma CLI to deploy migrations before replacing the shell process with node dist/src/main.
• Blue-green rollout strategy is documented in docs/MIGRATION_RUNBOOK.md.
• Recommended alerts:
  • 5xx rate > 2% for 5 minutes
  • p95 latency > 2.5s for 10 minutes
  • event publish failures > 0.5% for 5 minutes
  • DB pool saturation > 85%

Open findings are tracked inline with TODO (security) comments in source.

Summary from docs/DEPENDENCIES.md:

• Production audit: no known vulnerabilities.
• Node 26.5.1, NestJS 11.1.28, Prisma 7.9.0, Axios 1.18.1, Lodash 4.18.1, qs 6.15.3, and UUID 14.0.1 are locked in the security candidate.
• Security overrides for affected transitives are maintained in pnpm-workspace.yaml and captured in pnpm-lock.yaml.
• Topcoder Git dependencies use immutable commits. Cross-service database dependencies install only committed generated Prisma clients rather than the full API applications and their unrelated dependency graphs.

Full details: docs/DEPENDENCIES.md.

Open TODO (quality) findings from prior phases:

• API prefix changed from /v5 to /v6.
• Elasticsearch removed; all reads use PostgreSQL via Prisma.
• Timeline/milestone CRUD intentionally not migrated (see docs/timeline-milestone-migration.md).
• Deprecated endpoints not ported (scope change requests, reports, customer payments, phase members/approvals, estimation items).
• Invite creation returns 201 when any invite is created and still uses { success: Invite[], failed: ErrorInfo[] } for rejected targets.
• Event originator changed from tc-project-service to project-service-v6.

Full details: docs/DIFFERENCES_FROM_V5.md and docs/MIGRATION_FROM_TC_PROJECT_SERVICE.md.

Migration runbook (phased rollout, rollback, monitoring): docs/MIGRATION_RUNBOOK.md.