stemedb/applications/aphoria/dogfood/httpclient/README.md

HTTP Client Library (httpclient) - Project 2

Status: Ready to start (Project 1 complete) Purpose: Demonstrate Aphoria's autonomous flywheel through pattern reuse from dbpool Duration: 4 days (faster than Project 1's 5 days due to skills + pattern reuse)

---

What Makes This Different from Project 1

Project 1 (dbpool): Established baseline

• Created 27 claims from scratch (manual workflow, 4 hours)
• 2-3 naming errors to fix
• Manual CLI workflow

Project 2 (httpclient): Demonstrates flywheel

• Reuse 8-10 claims from dbpool (skills-driven, 1-2 hours)
• 0 naming errors (skills enforce consistency)
• Autonomous workflow via skills

Expected Results:

• 50-60% time reduction for Day 1
• 40% pattern reuse
• 100% naming consistency

---

Quick Start

Pre-Flight Check

# Verify Project 1 corpus exists
curl 'http://localhost:18180/v1/aphoria/corpus' | \
  jq '[.items[] | select(.subject | contains("dbpool"))] | length'
# Must return: 27

# Verify skills installed
ls -la ~/.claude/skills/ | grep aphoria | wc -l
# Must return: 8

If both pass: You're ready to start

If either fails: Complete Project 1 first or install skills

---

What We're Building

httpclient: Production-ready HTTP client library with connection pooling, timeout management, and TLS enforcement.

Why This Project:

1. Shares patterns with dbpool: connection_timeout, TLS config, metrics
2. Demonstrates flywheel: Skills discover existing patterns, enforce aligned naming
3. Real violations: timeout cascades, redirect loops, TLS bypasses
4. Measurable ROI: "50% faster due to pattern reuse" + "Aphoria prevented production timeout cascade"

---

7 Intentional Violations

1. Unbounded redirect limit (should be ≤10)
2. Excessive request timeout (120s vs 30s max)
3. Excessive connection timeout (60s vs 10s max)
4. Missing idle timeout (connections never expire)
5. TLS verification disabled (MITM vulnerability)
6. TLS version too low (TLS 1.0 vs 1.2 minimum)
7. No retry limit (retry storms amplify failures)

All violations have clear consequences and alignment with dbpool patterns.

---

Pattern Reuse from dbpool

dbpool Pattern	httpclient Adaptation
connection_timeout: max 30s	request_timeout: max 30s
tls/enabled: required	tls/certificate_validation: required
tls/min_version: 1.2	tls/min_version: 1.2 (same)
max_connections: required	max_redirects: max 10 (bounded resource)
max_lifetime: required	idle_timeout: required (lifecycle)

Skills will discover these patterns automatically on Day 1.

---

Day-by-Day Plan

Day 1: Claims with Pattern Discovery (1-2 hours)

Use skills:

1. /aphoria-suggest - Discover reusable dbpool patterns
2. /aphoria-claims - Extract claims with enforced naming alignment

Target: 22 claims (8-10 reused, 12-14 new)

See: plan.md Day 1 for detailed workflow

---

Day 2: Implementation (4-5 hours)

Create library with 7 violations:

• src/config.rs - 5 violations
• src/client.rs - 2 violations

Document violations inline with // VIOLATION: comments

See: plan.md Day 2 for file structure

---

Day 3: Scan + Custom Extractors (2-3 hours)

Initial scan:

aphoria scan --persist --format json > scan-results-v1.json

If built-in extractors insufficient:

/aphoria-custom-extractor-creator
"Generate extractors for these violations..."

Target: 7/7 violations detected

See: plan.md Day 3 for extractor generation

---

Day 4: Remediation (4-5 hours)

Fix violations incrementally:

• Fix 1 → scan-v2.json
• Fix 2 → scan-v3.json
• ...
• Fix 7 → scan-v8.json (0 conflicts)

Git commit after each fix with context

See: plan.md Day 4 for remediation workflow

---

Day 5: Documentation (3-4 hours)

Create:

• SUCCESS-STORY.md - Flywheel metrics and evidence
• DEMO-SCRIPT.md - Stakeholder presentation

Document:

• Time savings: 60%+ reduction
• Pattern reuse: 40%+ claims
• Naming consistency: 100%

See: plan.md Day 5 for documentation requirements

---

Success Criteria

Minimum (Proves Skills Work)

• ✅ Day 1 in <2 hours (vs 4 hours)
• ✅ 8+ claims reused from dbpool
• ✅ 0 naming errors
• ✅ 7/7 violations detected

Full (Proves Flywheel Works)

• ✅ All of above, plus:
• ✅ Skills generated all extractors
• ✅ Documented flywheel value:
  • Time: 60%+ faster
  • Reuse: 40%+ patterns
  • Consistency: 100% aligned

---

Files

Planning:

• plan.md - Complete 5-day plan
• CHECKLIST.md - Day-by-day execution (similar to dbpool)
• README.md - This file

Authority Sources (fetch on Day 1):

• docs/sources/http-rfcs.md - RFC 7230-7235
• docs/sources/mozilla-http.md - Mozilla HTTP best practices
• docs/sources/requests-docs.md - Requests library patterns

Implementation (Day 2):

• src/ - HTTP client library with violations
• tests/ - Integration tests
• Cargo.toml - Dependencies

Evidence (Days 3-5):

• scan-results-v*.json - Progressive scan results
• SUCCESS-STORY.md - Flywheel demonstration
• DEMO-SCRIPT.md - Presentation guide

---

Documentation

Detailed plan: plan.md Execution checklist: CHECKLIST.md (reference dbpool's with Project 2 context) Pattern reuse guide: ../dbpool/docs/multi-project-setup.md

---

Ready to Start?

1. ✅ Verify pre-flight checks pass (27 dbpool claims, 8 skills)
2. ✅ Read plan.md for complete context
3. ✅ Start Day 1 with /aphoria-suggest to discover patterns

The flywheel is ready. Project 2 will prove it works.