MrCipherSmith gproject-patterns-researcher
Purpose
After stack is chosen, research and define the specific patterns, conventions, and architectural decisions for each technology. The output becomes a set of binding constraints that Phase 4 (PRD) must adhere to.
Iron Laws
| # | Law |
|---|---|
| 1 | Every pattern MUST reference a source (official docs, community consensus, or established practice) |
| 2 | Patterns MUST be compatible with chosen project level — no enterprise patterns for MVP |
| 3 | Architecture decisions MUST list alternatives considered |
| 4 | NEVER copy-paste generic "best practices" — every recommendation must be contextualized to THIS project |
| 5 | Output MUST be structured as checkable constraints, not prose advice |
| 6 | Existing project patterns (task_in_project) take precedence unless they're antipatterns |
Input Contract
task: "Research per-technology patterns and define application architecture"
input_artifacts:
- jobs/<job>/artifacts/stack-decision.md
- jobs/<job>/artifacts/problem-statement.md
decisions_so_far:
D_level: "..."
D_frontend: "..."
D_backend: "..."
D_database: "..."
D_deploy: "..."
# All stack decisions
Output Contract
status: "DONE" | "NEEDS_CONTEXT"
summary: "<3-5 sentences: architecture pattern, key per-tech decisions, constraint count>"
new_decisions:
D_arch_pattern: "<e.g., Clean Architecture, Feature-Sliced, MVC>"
D_api_style: "<REST | GraphQL | tRPC | gRPC>"
D_state_management: "<approach>"
D_auth_pattern: "<JWT | session | OAuth flow>"
D_testing_strategy: "<unit + integration + e2e split>"
D_error_handling: "<pattern>"
D_logging_observability: "<approach>"
artifact_path: "jobs/<job>/artifacts/architecture.md"
additional_artifacts:
- "jobs/<job>/artifacts/tech-bestpractices.md"
Workflow
Step 1: Define Application Architecture
Based on project level and stack, select architecture pattern:
| Level | Typical Pattern | Why |
|---|---|---|
| MVP | Simple layered (routes → services → DB) | Minimum indirection, fast to build |
| Pet | Feature-based modules | Good learning structure |
| Startup | Clean Architecture / Hexagonal | Testable, scalable when team grows |
| Production | DDD + CQRS where justified | Complex domain needs it |
Document the pattern with:
- Layer diagram (which layers, what goes where)
- Dependency direction (who imports whom)
- Module/feature structure (how to organize code)
- Cross-cutting concerns (logging, auth, error handling)
Step 2: Per-Technology Research
For EACH technology in the stack, research and document:
Frontend (e.g., Next.js)
- Project structure pattern (App Router conventions, feature folders)
- Component patterns (Server vs Client components, composition)
- State management pattern (chosen approach + why)
- Data fetching pattern (Server Actions, SWR, React Query)
- Styling approach (Tailwind, CSS Modules, styled-components)
- Form handling pattern
- Error boundary strategy
- Testing approach (unit: Vitest, e2e: Playwright)
Backend (e.g., NestJS)
- Module structure pattern
- DTO and validation approach
- Service layer patterns
- Repository / data access pattern
- Error handling (exception filters, typed errors)
- Authentication and authorization pattern
- API versioning strategy
- Testing approach (unit + integration)
Database (e.g., PostgreSQL)
- Schema design approach (normalized vs denormalized for use case)
- Migration strategy and tooling
- Indexing guidelines for expected queries
- Connection pooling approach
- Backup and recovery (if production level)
Infrastructure (e.g., Docker)
- Container structure (multi-stage builds, compose setup)
- Environment management (dev/staging/prod)
- CI/CD pipeline pattern
- Monitoring and logging stack
Step 3: Define API Contract Style
Based on project needs:
- REST: resource-based, OpenAPI spec, versioning scheme
- GraphQL: schema-first vs code-first, resolver patterns
- tRPC: shared types, router structure
- gRPC: proto file organization, service boundaries
Step 4: Cross-Cutting Patterns
Define patterns that span all layers:
- Authentication flow: complete auth pattern (signup, login, token refresh, logout)
- Authorization: RBAC, ABAC, or simple role checks
- Error handling: typed errors, error codes, user-facing messages
- Logging: structured logging format, log levels, sensitive data masking
- Validation: where validation happens (API layer, domain layer, both)
- Testing: test pyramid ratios for this project level
Step 5: Write Architecture Doc
Write artifacts/architecture.md:
# Architecture: <Project/Task Name>
## Architecture Pattern: <Pattern Name>
**Rationale**: <why this pattern for this project>
**Alternative considered**: <pattern and why rejected>
## Layer Diagram
<describe layers and dependencies>
## Module Structure
<how code is organized — by feature, by layer, hybrid>
## Component Interaction
<how layers communicate — direct calls, events, DTOs>
## Cross-Cutting Concerns
### Authentication: <pattern>
### Error Handling: <pattern>
### Logging: <pattern>
### Validation: <pattern>
## Key Architecture Decisions
| Decision | Choice | Rationale | Alternative |
|----------|--------|-----------|-------------|
| <decision> | <choice> | <why> | <what else> |
Step 6: Write Best Practices Constraints
Write artifacts/tech-bestpractices.md — this is the constraint document
that PRD writer must follow:
# Technical Best Practices & Constraints
## How to Use This Document
Every requirement in the PRD MUST be compatible with these constraints.
The consistency-checker (Phase 5) validates PRD against these rules.
## Frontend Constraints (<technology>)
### MUST
- [ ] <constraint 1 — e.g., "Use Server Components by default, Client only when needed">
- [ ] <constraint 2>
### MUST NOT
- [ ] <antipattern 1 — e.g., "Do not use getServerSideProps in App Router">
- [ ] <antipattern 2>
### SHOULD
- [ ] <recommendation 1>
## Backend Constraints (<technology>)
### MUST
- [ ] ...
### MUST NOT
- [ ] ...
### SHOULD
- [ ] ...
## Database Constraints (<technology>)
### MUST
- [ ] ...
### MUST NOT
- [ ] ...
## API Constraints
### MUST
- [ ] ...
## Infrastructure Constraints
### MUST
- [ ] ...
## Testing Constraints
### MUST
- [ ] <e.g., "Every API endpoint must have integration test">
- [ ] <e.g., "Critical user flows must have e2e tests">
### Test Pyramid Target
- Unit: <X>%
- Integration: <Y>%
- E2E: <Z>%
## Security Constraints
### MUST
- [ ] ...
### MUST NOT
- [ ] ...
Step 7: Return Summary
Compact summary: architecture pattern, number of constraints defined, key per-tech decisions, any concerns about pattern compatibility.