COMPLETE OUTPUT
Every file. Nothing redacted.
A freelance marketplace described in one conversation. Browse 11 of the most important files here — PrimaSpec generated up to 26 in total, including IDE configs, CI/CD, stubs, and deployment manifests. This is what your AI agent reads on day one.
freelancehub-spec.json
11
entities
34
endpoints
15
business rules
15 min
conversation
# CLAUDE.md — FreelanceHub Behavioral Contract v1.0.0
> Conflict Resolution: This file wins over all other files.
> Session Init: Read CLAUDE.md, then AGENTS.md, then BLUEPRINT.md at every session start.
---
## Mandatory Plan Rule (Non-Negotiable)
Any change that is a feature addition, refactor, or multi-file modification MUST follow:
1. Create a plan in plans/{NNN}-{slug}.md following plans/000-template.md
2. Execute immediately without waiting for approval between steps
3. Every mandatory section from the template must be present
4. After execution: verify:fast, commit, push, deploy. No exceptions.
The only exception is the Micro-Fix Exception below (under 3 lines, single file, zero
security implications).
---
## Critical Invariants (Non-Negotiable)
1. BOLA Prevention: Never `findUnique(id)` on client-supplied IDs.
Always scope by `userId` or `tenantId`. Return 404 on ownership mismatch.
2. Escrow Integrity: All payment mutations go through EscrowService.
No direct Stripe calls outside this service. Every state transition
(funded, released, disputed, refunded) writes an EscrowEvent audit row.
3. Dispute Fairness: When a dispute opens, funds freeze immediately.
Neither party receives payment until resolution. Admin or arbitration
panel decides. Partial splits are supported.
4. Auth Chain: JWT access token (15min) + HTTP-only refresh token (7d).
Guard hierarchy: Public > Authenticated > Freelancer > Client > Admin.
5. Payment Processing: Stripe Connect for payouts. Platform fee is 12%.
Freelancer onboarding requires Stripe Connect account verification
before accepting jobs.
6. Rating Integrity: Reviews are immutable after 48 hours. One review
per completed contract per party. No edits, no deletes.
7. Input Validation: Every endpoint validates input via class-validator DTOs
with whitelist: true and forbidNonWhitelisted: true.
8. Token Costs: Every Stripe API call must record usage. Duplicate webhook
events must be idempotently processed.
---
## Phase Protocol
1. Read BLUEPRINT.md for current phase requirements
2. Check STATE.md for progress and next step
3. Implement one status mark at a time
4. Run verify:fast after every change
5. Update STATE.md before moving to the next step
---
## Module Boundaries
| Module | Owns | Forbidden |
|----------------|-----------------------------------|-----------------------------------|
| auth | JWT, guards, sessions | Business logic, DB queries |
| user | Profile, settings, onboarding | Payment, escrow |
| job | Listings, search, categories | Payment, contracts |
| proposal | Bids, negotiation, acceptance | Payment, delivery |
| contract | Milestones, deliverables, status | User profiles, job listings |
| escrow | Stripe, funds, disputes, payouts | Everything else |
| review | Ratings, feedback, aggregation | Payment, contracts |
| notification | Email, in-app, webhooks | Business logic |
---
## Naming Conventions
| Layer | Pattern | Example |
|-------------|---------------------------|----------------------------|
| Controller | {Entity}Controller | JobController |
| Service | {Entity}Service | EscrowService |
| DTO | {Action}{Entity}Dto | CreateJobDto |
| Entity | PascalCase singular | Milestone |
| Table | snake_case plural | escrow_transactions |
| Endpoint | /api/{resource} | /api/jobs/:id/proposals |
| Guard | {Role}Guard | FreelancerGuard |
| Event | {entity}.{action} | contract.completed |
| Test file | {entity}.e2e-spec.ts | escrow.e2e-spec.ts |
---
## Anti-Patterns
NEVER do any of the following:
- Use `findUnique` on user-supplied IDs without ownership check
- Call Stripe API directly outside EscrowService
- Skip DTO validation on controller inputs
- Return 403 for BOLA failures (use 404 to prevent enumeration)
- Store secrets in client-accessible state or local storage
- Commit .env files, API keys, or Stripe webhook secrets
- Use string interpolation for SQL queries (use Prisma parameterized)
- Import from internal module files (use index re-exports only)
- Catch errors silently (always log and re-throw or return error response)
- Use `any` type (use `unknown` with type guards)
- Skip E2E tests for new endpoints
- Deploy without running verify:fast
---
## Concurrency Safety
- Escrow fund + release must use database transactions
- Proposal acceptance must reject all other proposals atomically
- Milestone approval must check escrow status inside the same transaction
- Use optimistic locking on Contract.status to prevent race conditions
- Job status transitions are guarded by current-state checks
---
## Performance Budget
| Metric | Target |
|-----------------------|-------------------|
| API p95 latency | < 200ms |
| Time to first byte | < 100ms |
| DB queries per request| <= 5 |
| Max payload size | 1MB |
| Connection pool | 20 connections |
---
## Error Response Contract
All errors follow this shape:
```json
{
"statusCode": 404,
"message": "Resource not found",
"code": "JOB_NOT_FOUND",
"requestId": "req_abc123"
}
```
Never return stack traces in production. Never expose internal IDs in error messages.
Log the full error server-side with requestId for debugging.
---
## Essential Commands
```bash
pnpm verify:fast # typecheck + lint + build (quality gate)
pnpm prisma:migrate # run pending migrations
pnpm prisma:seed # seed database with test data
pnpm dev # start API + web dev servers
pnpm test:e2e # full E2E suite (needs PostgreSQL + Redis)
pnpm build # production build
```
---
## Git Protocol
- Feature branches: feature/{SM-number}-{slug}
- Commit format: [SM-{N}] {imperative description}
- Never force push to main
- Never amend published commits
- Run verify:fast before every commit
- Stage specific files, not git add -A
---
## Context Recovery Protocol
If you lose context mid-build:
1. Read STATE.md for current phase and step
2. Read CLAUDE.md (this file) for rules
3. Read the last plan in plans/ for current task
4. Continue from where STATE.md indicates
---
## Governance Files
Read order:
1. CLAUDE.md -- Behavioral contract (this file)
2. AGENTS.md -- Quick-reference domain model
3. AGENTS-full.md -- Deep indexed reference (AGF:: tokens)
4. BLUEPRINT.md -- Phase-by-phase build plan
5. STATE.md -- Live progress tracker
6. FEATURES.md -- Feature inventory
7. .cursor/rules/spec.mdc -- Cursor agent config
---
*Generated by [PrimaSpec](https://primaspec.com). AI-driven architecture specs.*WHAT EACH FILE DOES
CLAUDE.md
The behavioral contract. Your agent reads this first and follows its rules for the entire build. Invariants, module boundaries, command reference.
BLUEPRINT.md
The build plan. Every phase, every step, every acceptance criterion. Your agent follows this sequence and checks off items as it builds.
AGENTS.md
The quick-reference sheet. Entity schemas, naming conventions, auth matrix, business rules, error codes. Your agent looks here for answers before asking you.
STATE.md
The progress tracker. Which phases are done, which steps remain, where the agent left off. Session crashes lose nothing because state is in the file.
FEATURES.md
The feature inventory. Every feature with its priority, phase assignment, and detailed requirements. Nothing gets forgotten halfway through.
THREATS.md
The STRIDE threat model. Every attack surface analyzed with mitigations and residual risk ratings. Security is designed in, not bolted on.