EasyPlatform architecture-design

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

AI Mistake Prevention — Failure modes to avoid on every task:

• Check downstream references before deleting. Deleting components causes documentation and code staleness cascades. Map all referencing files before removal.
• Verify AI-generated content against actual code. AI hallucinates APIs, class names, and method signatures. Always grep to confirm existence before documenting or referencing.
• Trace full dependency chain after edits. Changing a definition misses downstream variables and consumers derived from it. Always trace the full chain.
• Trace ALL code paths when verifying correctness. Confirming code exists is not confirming it executes. Always trace early exits, error branches, and conditional skips — not just happy path.
• When debugging, ask "whose responsibility?" before fixing. Trace whether bug is in caller (wrong data) or callee (wrong handling). Fix at responsible layer — never patch symptom site.
• Assume existing values are intentional — ask WHY before changing. Before changing any constant, limit, flag, or pattern: read comments, check git blame, examine surrounding code.
• Verify ALL affected outputs, not just the first. Changes touching multiple stacks require verifying EVERY output. One green check is not all green checks.
• Holistic-first debugging — resist nearest-attention trap. When investigating any failure, list EVERY precondition first (config, env vars, DB names, endpoints, DI registrations, data preconditions), then verify each against evidence before forming any code-layer hypothesis.
• Surgical changes — apply the diff test. Bug fix: every changed line must trace directly to the bug. Don't restyle or improve adjacent code. Enhancement task: implement improvements AND announce them explicitly.
• Surface ambiguity before coding — don't pick silently. If request has multiple interpretations, present each with effort estimate and ask. Never assume all-records, file-based, or more complex path.

MANDATORY IMPORTANT MUST ATTENTION use

TaskCreate

AskUserQuestion

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in

plans/reports/

— prevents context loss and serves as deliverable.

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, and recommendation requires

file:line

proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

Quick Summary

Goal: Act as a solution architect — research, critically analyze, and recommend the complete technical architecture for a project or feature. Cover ALL architecture concerns: backend, frontend, design patterns, library ecosystem, testing strategy, CI/CD, deployment, monitoring, code quality, and dependency management. Produce a comprehensive comparison report with actionable recommendations.

Workflow (12 steps):

1. Load Context — Read domain model, tech stack, business evaluation, refined PBI
2. Derive Architecture Requirements — Map business/domain complexity to architecture constraints
3. Backend Architecture — Research top 3 backend architecture styles + design patterns
4. Frontend Architecture — Research top 3 frontend architecture styles + design patterns
5. Library Ecosystem Research — Best-practice libraries per concern (validation, caching, logging, utils, etc.)
6. Testing Architecture — Unit, integration, E2E, performance testing frameworks + strategy
7. CI/CD & Deployment — Pipeline design, containerization, orchestration, IaC
8. Observability & Monitoring — Logging, metrics, tracing, alerting stack
9. Code Quality & Clean Code — Linters, analyzers, formatters, enforcement tooling
10. Dependency Risk Assessment — Package health, obsolescence risk, maintenance cost
11. Generate Report — Full architecture decision report with all recommendations
12. User Validation — Present findings, ask 8-12 questions, confirm all decisions

Key Rules:

• MANDATORY IMPORTANT MUST ATTENTION research minimum 3 options per architecture concern with web evidence
• MANDATORY IMPORTANT MUST ATTENTION include confidence % with evidence for every recommendation
• MANDATORY IMPORTANT MUST ATTENTION run user validation interview at end (never skip)
• Delegate to

  solution-architect

  agent for complex architecture decisions
• All claims must cite sources (URL, benchmark, case study, or codebase evidence)
• Never recommend based on familiarity alone — evidence required

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Step 1: Load Context

Read artifacts from prior workflow steps (search in

plans/

team-artifacts/

• Domain model / ERD (complexity, bounded contexts, aggregate count)
• Tech stack decisions (confirmed languages, frameworks, databases)
• Business evaluation (scale, constraints, compliance)
• Refined PBI (scope, acceptance criteria)
• Discovery interview (team skills, experience level)

Extract and summarize:

Step 2: Derive Architecture Requirements

Map signals to architecture constraints:

MANDATORY IMPORTANT MUST ATTENTION validate derived requirements with user via

AskUserQuestion

Step 3: Backend Architecture

3A: Architecture Styles

WebSearch top 3 backend architecture styles. Candidates:

3B: Backend Design Patterns

Evaluate applicability per layer:

For each recommended pattern, document: Apply to, Why, Example, Risk if skipped.

Step 4: Frontend Architecture

4A: Architecture Styles

WebSearch top 3 frontend architecture styles. Candidates:

4B: Frontend Design Patterns

Step 4B: UI System Architecture

Skip if: Backend-only project, no frontend component.

Research and recommend the project's design system architecture. Use

AskUserQuestion

4B-1: Styling Approach

WebSearch top 3 styling approaches for the confirmed frontend framework:

4B-2: Design Token Strategy

--color-primary

--btn-bg

4B-3: Component Library Strategy

4B-4: Responsive Strategy

MANDATORY IMPORTANT MUST ATTENTION validate all UI system decisions with user via

AskUserQuestion

Step 5: Library Ecosystem Research

For EACH concern below, WebSearch top 3 library options for the confirmed tech stack. Evaluate: maturity, community, bundle size, maintenance activity, license, learning curve.

Library Concerns Checklist

Per-Library Evaluation Template

### {Concern}: Top 3 Options

| Criteria         | Option A          | Option B | Option C |
| ---------------- | ----------------- | -------- | -------- |
| GitHub Stars     | ...               | ...      | ...      |
| Last Release     | ...               | ...      | ...      |
| Bundle Size      | ...               | ...      | ...      |
| Weekly Downloads | ...               | ...      | ...      |
| License          | ...               | ...      | ...      |
| Maintenance      | Active/Slow/Stale | ...      | ...      |
| Learning Curve   | Low/Med/High      | ...      | ...      |

**Recommendation:** {Option} — Confidence: {X}%

Step 6: Testing Architecture

Research best testing tools and strategy for the confirmed tech stack:

Test Strategy Template

### Test Pyramid

- **Unit (70%):** {framework} — {what to test}
- **Integration (20%):** {framework} — {what to test}
- **E2E (10%):** {framework} — {what to test}

### Coverage Targets

- Unit: {X}% | Integration: {X}% | E2E: critical paths only
- Enforcement: {tool} in CI pipeline, fail build below threshold

Step 7: CI/CD & Deployment

Research deployment architecture and CI/CD tooling:

Deployment Strategy Comparison

Step 8: Observability & Monitoring

Observability Decision: 3 Pillars

### Recommended Observability Stack

| Pillar   | Tool   | Why         |
| -------- | ------ | ----------- |
| Logs     | {tool} | {rationale} |
| Metrics  | {tool} | {rationale} |
| Traces   | {tool} | {rationale} |
| Alerting | {tool} | {rationale} |

Step 9: Code Quality & Clean Code Enforcement

Research and recommend tooling for automated code quality:

Enforcement Strategy

### Code Quality Gates

| Gate        | Tool   | Trigger        | Fail Criteria         |
| ----------- | ------ | -------------- | --------------------- |
| Pre-commit  | {tool} | git commit     | Lint errors, format   |
| PR Check    | {tool} | Pull request   | Coverage < X%, issues |
| CI Pipeline | {tool} | Push to branch | Build fail, test fail |
| Scheduled   | {tool} | Weekly/nightly | Security vulns, debt  |

Scaffold Handoff (MANDATORY — consumed by

/scaffold

)

After completing code quality research, produce this handoff table in the architecture report. The

/scaffold

### Scaffold Handoff — Tool Choices

| Concern        | Chosen Tool       | Config File | Rationale |
| -------------- | ----------------- | ----------- | --------- |
| Linter (FE)    | {tool}            | {filename}  | {why}     |
| Linter (BE)    | {tool}            | {filename}  | {why}     |
| Formatter      | {tool}            | {filename}  | {why}     |
| Pre-commit     | {tool}            | {filename}  | {why}     |
| Error handling | {pattern}         | {files}     | {why}     |
| Loading state  | {pattern}         | {files}     | {why}     |
| Docker         | {compose pattern} | {files}     | {why}     |

Also include: Error handling strategy (4-layer pattern), loading state approach (global vs per-component), and Docker profile structure. Specific tool choices →

docs/project-reference/

project-config.json

Step 10: Dependency Risk Assessment

For EVERY recommended library/package, evaluate maintenance and obsolescence risk:

Package Health Scorecard

npm ls --depth

Risk Categories

Dependency Maintenance Strategy

### Recommended Practices

1. **Automated scanning:** {tool} (Dependabot/Renovate/Snyk) — weekly PR for updates
2. **Lock file strategy:** Commit lock files, pin major versions, allow patch auto-update
3. **Audit schedule:** Monthly `npm audit` / `dotnet list package --vulnerable`
4. **Vendor policy:** Max {N} dependencies per concern, prefer well-maintained alternatives
5. **Exit strategy:** For each High-risk dependency, document migration path to alternative

Step 11: Generate Report

Write report to

{plan-dir}/research/architecture-design.md

1. Executive summary (recommended architecture in 8-10 lines)
2. Architecture requirements table (from Step 2)
3. Backend architecture — style comparison + recommended patterns (Steps 3)
4. Frontend architecture — style comparison + recommended patterns (Step 4)
5. Library ecosystem — per-concern recommendations with alternatives (Step 5)
6. Testing architecture — pyramid, tools, coverage targets (Step 6)
7. CI/CD & deployment — pipeline design, deployment strategy (Step 7)
8. Observability stack — 3 pillars + alerting (Step 8)
9. Code quality — enforcement gates, tooling (Step 9)
10. Dependency risk matrix — high-risk packages, mitigation (Step 10)
11. Architecture diagram (Mermaid — showing all layers and data flow)
12. Risk assessment for overall architecture
13. Unresolved questions

Architecture Diagram Template

```mermaid
graph TB
    subgraph "Frontend"
        UI[SPA / Micro Frontend]
        STORE[State Management]
    end
    subgraph "API Gateway"
        GW[Gateway / BFF]
    end
    subgraph "Backend Services"
        CMD[Commands / Handlers]
        QRY[Queries / Read Models]
        SVC[Domain Services]
        ENT[Entities / Aggregates]
    end
    subgraph "Infrastructure"
        DB[(Database)]
        CACHE[(Cache)]
        MSG[Message Bus]
        SEARCH[(Search Index)]
    end
    subgraph "Observability"
        LOG[Logging]
        METRIC[Metrics]
        TRACE[Tracing]
    end
    subgraph "CI/CD"
        PIPE[Pipeline]
        REG[Container Registry]
        K8S[Orchestration]
    end
    UI --> GW --> CMD & QRY
    CMD --> SVC --> ENT --> DB
    QRY --> CACHE & SEARCH
    ENT -.-> MSG
    CMD & QRY -.-> LOG & METRIC & TRACE
    PIPE --> REG --> K8S
```

Step 12: User Validation Interview

MANDATORY IMPORTANT MUST ATTENTION present findings and ask 8-12 questions via

AskUserQuestion

Required Questions

1. Backend architecture — "I recommend {style}. Agree?"
2. Frontend architecture — "I recommend {style} with {state management}. Agree?"
3. Design patterns — "Recommended backend patterns: {list}. Frontend patterns: {list}. Any to add/remove?"
4. Key libraries — "For {concern}, I recommend {lib} over {alternatives}. Agree?"
5. Testing strategy — "Test pyramid: {unit}%/{integration}%/{E2E}% using {frameworks}. Appropriate?"
6. CI/CD — "Pipeline: {tool} with {deployment strategy}. Fits your infra?"
7. Observability — "Monitoring stack: {logs}/{metrics}/{traces}. Sufficient?"
8. Code quality — "Enforcement: {linter + formatter + pre-commit hooks}. Team ready?"
9. Dependency risk — "Found {N} high-risk dependencies. Accept or find alternatives?"
10. Complexity check — "This architecture has {N} concerns addressed. Appropriate for team size?"

Optional Deep-Dive Questions (pick 2-3)

• "Should we use event sourcing or traditional state-based persistence?"
• "Monolith-first or start with service boundaries?"
• "Micro frontends or monolith SPA?"
• "How important is framework independence for this project?"
• "Self-hosted observability or managed SaaS?"
• "Strict lint rules from day 1 or gradual adoption?"

After user confirms, update report with final decisions and mark as

status: confirmed

Best Practices Audit (applied across all steps)

Validate architecture against these principles — flag violations in report:

new

Output

{plan-dir}/research/architecture-design.md     # Full architecture analysis report
{plan-dir}/phase-02b-architecture.md           # Confirmed architecture decisions

MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using

TaskCreate

AskUserQuestion

Next Steps

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing this skill, you MUST ATTENTION use

AskUserQuestion

• "/plan (Recommended)" — Create implementation plan from architecture design
• "/refine" — If need to create PBIs first
• "Skip, continue manually" — user decides

Closing Reminders

MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using

TaskCreate

AskUserQuestion

• MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact. <!-- /SYNC:critical-thinking-mindset:reminder --> <!-- SYNC:ai-mistake-prevention:reminder -->
• MUST ATTENTION apply AI mistake prevention — holistic-first debugging, fix at responsible layer, surface ambiguity before coding, re-read files after compaction. <!-- /SYNC:ai-mistake-prevention:reminder -->