Project Reference Patterns (PRPs)¶

PRPs are living documents that capture reusable patterns, anti-patterns, and implementation guidelines for Chaverim ALPR Platform.

What are PRPs?¶

Project Reference Patterns provide: - Reusable solutions to common problems - Anti-patterns to avoid - Implementation guides with examples - Context for why patterns were chosen

PRPs are created when patterns emerge from actual implementation, not defined upfront. They're extracted from docs/phases/ decision logs and successful implementations.

When to Create a PRP¶

✅ Create a PRP when: - A pattern is used in 2+ places - A complex feature (>1 day) has a proven approach - An anti-pattern is discovered and needs documentation - A decision has broad implications across components - A pattern would benefit future development or AI assistants

❌ Don't create a PRP for: - One-off implementations - Framework-standard patterns (already documented elsewhere) - Obvious or trivial patterns - Patterns still being refined

PRP Structure¶

1. Global PRP (`global.md`)¶

Purpose: Patterns that apply to ALL components and features.

Contains: - Cross-cutting concerns (security, logging, error handling) - Project-wide conventions (naming, file structure) - Universal anti-patterns - Integration patterns (database, external services)

Check this FIRST before implementing any feature.

2. Component-Specific PRPs¶

Purpose: Patterns for specific domains or components.

Naming: [component-name]-prp.md (e.g., authentication-prp.md, payment-prp.md)

Contains: - Component-specific patterns - Domain-specific anti-patterns - Implementation task lists - Integration points with other components

Using PRPs¶

Before Implementing a Feature¶

Check global.md first - Global patterns apply everywhere
Check for component PRP - Look for [component]-prp.md
Review relevant sections:
Task List (what to implement)
Anti-Patterns (what to avoid)
Patterns (how to implement)
Follow closely - PRPs are proven approaches

When Implementing¶

Reference PRPs in code comments - Link to relevant PRP sections
Follow task lists - Use as implementation checklist
Adapt as needed - PRPs are guidelines, not strict rules
Note deviations - Document why you diverged from PRP

After Implementing¶

Update PRPs - Add newly discovered patterns
Refine existing patterns - Improve based on experience
Add examples - Show real implementation code
Extract from phase docs - Promote patterns from decisions.md

Creating a New PRP¶

1. Copy Template¶

cp docs/prp/component-template.md docs/prp/[component-name]-prp.md

2. Customize Sections¶

Overview - What this component does
Task List - Implementation checklist
Patterns - Proven approaches
Anti-Patterns - Common mistakes
Integration - How it connects to other components
Testing - Test strategies
Examples - Real code samples

3. Extract from Phase Docs¶

Review docs/phases/phase-X/decisions.md for: - Repeated decisions - Architectural patterns - Lessons learned

Promote to PRP if reusable.

4. Link from CLAUDE.md¶

Add reference in CLAUDE.md:

### Check PRPs Before Implementing

1. Check `docs/prp/global.md` first (applies to ALL components)
2. Check for component-specific PRP in `docs/prp/` directory

PRP Maintenance¶

Regular Reviews¶

After each phase - Extract patterns from decisions
When patterns emerge - Document as soon as 2nd use appears
When anti-patterns found - Document immediately to prevent repetition

Keeping PRPs Current¶

Update with new patterns - Add as project evolves
Refine existing patterns - Improve clarity and examples
Archive obsolete patterns - Mark deprecated and provide alternatives
Add examples - Show real implementations, not theoretical code

Quality Guidelines¶

✅ Good PRPs: - Concrete and actionable - Include real code examples - Explain WHY not just WHAT - Link to related patterns - Show anti-patterns with explanations

❌ Poor PRPs: - Vague or theoretical - No examples - Just say "do this" without context - Duplicate framework documentation - Never updated after creation

PRP Directory Structure¶

docs/prp/
├── README.md                    # This file - PRP system overview
├── global.md                    # Global patterns (CHECK FIRST!)
├── component-template.md        # Template for new PRPs
│
├── database-prp.md              # SQLAlchemy models, migrations, schema namespacing
├── camera-adapters-prp.md       # Camera vendor adapters, detection normalization
├── websocket-prp.md             # WebSocket connections, message formats, reconnection
├── image-storage-prp.md         # MinIO storage, presigned URLs, lifecycle
├── edge-provisioning-prp.md     # Claim codes, device encryption, remote wipe
├── api-key-prp.md               # API key generation, validation, rotation
├── logging-prp.md               # Structured JSON logging, request tracing
├── ingest-service-prp.md        # Ingest service implementation patterns
├── traefik-prp.md               # Traefik reverse proxy, subdomain routing, SSL
└── ...                          # Additional component PRPs

Integration with Other Docs¶

PRPs relate to: - Phase docs (docs/phases/) - Source of patterns - PROJECT_TRACKER.md - References PRPs created - CLAUDE.md - Instructs to check PRPs before implementing - Test configs - PRPs inform testing strategies

Flow: 1. Implement feature → Log decision in phase docs 2. Pattern emerges (2nd use) → Extract to PRP 3. Future feature → Check PRP first → Follow pattern 4. Refine PRP based on experience

Examples of Good PRPs¶

Authentication PRP¶

OAuth flow pattern
Session management approach
Token refresh strategy
Common security pitfalls

API Design PRP¶

RESTful endpoint patterns
Error response format
Pagination approach
Versioning strategy

Database PRP¶

Migration patterns
Schema design principles
Query optimization approaches
Transaction handling

Tips for Effective PRPs¶

For Humans¶

Start small - Document one pattern well rather than many poorly
Use examples - Show actual code, not pseudocode
Explain trade-offs - Help readers understand when NOT to use pattern
Keep updated - Review and refine regularly

For Claude Code¶

Be explicit - State all assumptions and prerequisites
Provide checklists - Task lists Claude can follow
Show anti-patterns - Help Claude avoid mistakes
Link context - Reference decisions, phase docs, external resources

Common Pitfalls¶

❌ Over-documenting - PRPs for every tiny pattern ❌ Under-explaining - Just code with no context ❌ Never updating - PRPs become stale and misleading ❌ Copying framework docs - Document project patterns, not framework basics ❌ No examples - All theory, no practice

Archive Policy¶

When to archive a PRP: - Technology or approach deprecated - Pattern replaced by better approach - Component removed from project

How to archive: 1. Move to docs/prp/archive/ 2. Add "DEPRECATED" notice at top 3. Link to replacement pattern 4. Explain why deprecated 5. Keep for historical context

PRP Status Legend¶

Status	Meaning
🟢 Stable	Proven pattern, ready for use
🟡 In Development	Pattern being refined, may change
🔴 Deprecated	Replaced by better approach, see notes

Active PRPs: 10 - global.md - Cross-cutting patterns (check first!) - database-prp.md - SQLAlchemy, migrations, schema namespacing - camera-adapters-prp.md - Camera vendor integrations - websocket-prp.md - Real-time notifications - image-storage-prp.md - MinIO object storage - edge-provisioning-prp.md - Device provisioning and security - api-key-prp.md - API key authentication - logging-prp.md - Structured JSON logging, request tracing - ingest-service-prp.md - Unified ingest service patterns - traefik-prp.md - Reverse proxy, subdomain routing, SSL

Last Review: 2025-12-30 Next Review: 2026-03-30

Note on "Last Updated" fields: These dates are manually maintained. Consider using git history (git log -1 --format='%ai' <file>) for authoritative modification timestamps.