stemedb/applications/aphoria/dogfood/dbpool/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Aphoria Dogfood Project: Database Connection Pool (dbpool)

Purpose: Demonstrate Aphoria's code-level truth linting by building a PostgreSQL connection pool library with intentional violations, then using Aphoria to detect and guide remediation.

Status: 5-day dogfood project (see plan.md for detailed schedule)

Parent Project: This is a dogfood demonstration within the larger Aphoria/StemeDB project located at /home/jml/Workspace/stemedb/

Critical Context

What Makes This Project Special

This is not a normal implementation project. The workflow is:

1. Day 1: Create 25-30 authoritative claims in corpus database (HikariCP, PostgreSQL, OWASP best practices)
2. Day 2: Write working code that intentionally violates 7-8 of those claims
3. Day 3: Run aphoria scan to verify all violations are detected
4. Day 4: Fix violations incrementally, re-scanning after each fix
5. Day 5: Document the success story with before/after evidence

The violations are intentional and educational. When writing code in Days 1-2, we want to violate the claims to demonstrate detection.

The Two Modes

• Violation Mode (Day 2): Write code that deliberately violates best practices
• Remediation Mode (Day 4): Fix code to comply with all claims

Always check plan.md to understand which mode we're in.

Quick Start

Pre-Flight Check

Before starting the dogfood exercise, validate your environment:

./scripts/validate-setup.sh

This checks all prerequisites (Aphoria CLI, API running, corpus DB, extractors working) and shows you exactly what to fix if anything is missing.

Learn Claim Extraction

Read the complete walkthrough before creating claims:

cat docs/claim-extraction-example.md

This teaches you how to extract claims from prose documentation with:

• Complete worked example (HikariCP paragraph → 3 claims)
• Decision framework (what deserves to be a claim vs noise)
• Anti-patterns to avoid (too generic, no consequences)

Time: 15-20 minutes | Worth it: Prevents creating garbage claims

---

Development Commands

Corpus Management (Day 1)

# Create a claim in the corpus database
aphoria corpus create \
  --subject "dbpool/{component}/{property}" \
  --predicate "{required|recommended|bounded|minimum|maximum}" \
  --value "{value}" \
  --explanation "{What} MUST {do} because {why}. If {violation}, {consequence}." \
  --authority "{Source Name}" \
  --category "{safety|security|performance|architecture}" \
  --tier {0-3}

# Query corpus via API (requires stemedb-api running on :18180)
curl 'http://localhost:18180/v1/aphoria/corpus?sources[]=vendor&limit=100' | jq .

# Count claims for dbpool
curl 'http://localhost:18180/v1/aphoria/corpus?sources[]=vendor' | \
  jq '.items | map(select(.subject | startswith("dbpool"))) | length'

Build & Test (Day 2+)

# Build library
cargo build

# Run tests
cargo test

# Build release
cargo build --release

Aphoria Scanning (Day 3+)

Before Day 3: Configure flywheel mode (see docs/flywheel-setup.md)

# Persistent scan (enables pattern learning)
aphoria scan --persist

# Persistent with sync (contributes to community corpus)
aphoria scan --persist --sync

# Ephemeral scan (fast, in-memory, ~0.25s - no learning)
aphoria scan

# JSON output (for programmatic analysis)
aphoria scan --format json > scan-results-v1.json

# Markdown report (human-readable)
aphoria scan --format markdown > SCAN-REPORT-v1.md

# Table output (default, terminal-friendly)
aphoria scan --format table

Analyze Scan Results

# Count violations by severity
jq '.findings | group_by(.verdict) | map({verdict: .[0].verdict, count: length})' scan-results-v1.json

# Count BLOCK verdicts (critical violations)
jq '.findings | map(select(.verdict == "BLOCK")) | length' scan-results-v1.json

# List all findings with explanations
jq '.findings[] | {file, line, verdict, explanation}' scan-results-v1.json

Architecture

File Structure

applications/aphoria/dogfood/dbpool/
├── plan.md                      # Master plan with 5-day schedule
├── CHECKLIST.md                 # Execution checklist with templates
├── CLAUDE.md                    # This file
├── Cargo.toml                   # Rust library manifest
├── .aphoria/
│   └── config.toml              # Aphoria scan configuration
├── src/
│   ├── lib.rs                   # Library root
│   ├── config.rs                # PoolConfig (violations → fixes)
│   ├── pool.rs                  # ConnectionPool implementation
│   ├── connection.rs            # Connection wrapper
│   ├── metrics.rs               # Pool metrics (added in Day 4)
│   └── error.rs                 # Error types
├── tests/
│   └── basic.rs                 # Functionality tests
├── docs/
│   ├── claim-extraction-example.md  # COMPLETE WALKTHROUGH (read this first!)
│   ├── flywheel-setup.md            # Flywheel configuration guide
│   ├── sources/                     # Authority source documents
│   │   ├── hikaricp-config.md
│   │   ├── postgresql-pooling.md
│   │   └── owasp-credentials.md
│   ├── SUCCESS-STORY.md             # Case study (Day 5)
│   └── DEMO-SCRIPT.md               # Demo guide (Day 5)
├── scripts/
│   └── validate-setup.sh            # Pre-flight validator
└── scan-results-v*.json         # Progressive scan results

Expected Violations (Day 2-3)

#	Violation	Severity	Claim Violated
1	Unbounded max_connections: Option<usize>	BLOCK	dbpool/max_connections required
2	Plaintext password in connection string	BLOCK	dbpool/connection_string/password must_not_be plaintext
3	Missing max_lifetime	BLOCK	dbpool/max_lifetime required
4	Excessive connection_timeout (60s vs 30s max)	FLAG	dbpool/connection_timeout maximum 30
5	Zero min_connections (should be ≥2)	FLAG	dbpool/min_connections minimum 2
6	No connection validation before checkout	FLAG	dbpool/validation/frequency required on_checkout
7	No metrics exposed	WARNING	dbpool/metrics/enabled recommended
8	No leak detection threshold	WARNING	dbpool/leak_detection_threshold recommended

Target: 8/8 violations detected (100% accuracy), 0 false positives

Dependencies & Environment

Required Services

• stemedb-api running on :18180 with corpus database

  STEMEDB_CORPUS_DB_DIR=/home/jml/.aphoria/corpus-db target/release/stemedb-api
  

• Aphoria CLI installed and working

  aphoria --version  # Should show version
  

Rust Dependencies

[dependencies]
tokio = { version = "1", features = ["full"] }
tokio-postgres = "0.7"
serde = { version = "1", features = ["derive"] }
thiserror = "1"

Authority Tiers

Claims in the corpus use these authority tiers:

• Tier 0: Regulatory (RFCs, Standards) - Highest authority
• Tier 1: Clinical (OWASP, NIST) - Security/compliance
• Tier 2: Vendor (HikariCP, PostgreSQL) - Industry best practices
• Tier 3: Expert (Team policy) - Project-specific rules

Our claims use Tier 1 (OWASP A07) for security and Tier 2 (HikariCP, PostgreSQL) for safety/performance.

Git Workflow

Progressive Tagging (Day 4)

Each fix gets a tag for easy demo navigation:

# Initial state with violations
git tag v0.1.0-violations

# After each fix
git tag v0.2.0-fix-unbounded      # Fixed max_connections
git tag v0.3.0-fix-credentials    # Fixed plaintext password
git tag v0.4.0-fix-lifetime       # Fixed max_lifetime
git tag v0.5.0-fix-timeouts       # Fixed timeouts
git tag v0.6.0-fix-validation     # Added validation
git tag v0.7.0-fix-observability  # Added metrics

# Final state
git tag v1.0.0-production-ready   # All violations fixed

Commit Messages

# Format: fix(dbpool): <what> - <why/consequence prevented>
git commit -m "fix(dbpool): set max_connections to prevent unbounded growth

Aphoria detected missing max_connections configuration which would allow
unbounded connection growth and exhaust database connections under load.
Added required max_connections field with development default of 10.

Resolves: BLOCK violation from HikariCP claim (Tier 2)"

Success Metrics

Objective Targets

Metric	Target	How to Measure
Claims Extracted	25-30	curl corpus API | jq '.total_matching'
Violations Detected	7-8	jq '.findings | length' scan-results-v1.json
Detection Accuracy	100%	All intentional violations found, 0 false positives
Scan Performance	≤0.3s	time aphoria scan (ephemeral mode)
Final Scan Result	0 conflicts	scan-v6.json shows all PASS

Qualitative Outcomes

• Compelling Story: "Aphoria prevented 3 potential P0 incidents before first deployment"
• Educational Value: Each violation includes explanation of real-world consequence
• Production Ready: Final code is genuinely production-worthy (can be extracted as real library)
• Demonstrable: 5-minute demo shows clear value proposition

Critical Rules

1. Read plan.md First: Always check the plan to understand current phase and goals
2. Intentional Violations: Days 1-2 involve deliberately writing bad code (it's educational)
3. Progressive Fixes: Day 4 fixes violations one at a time with re-scans after each
4. Evidence Collection: Save all scan results (scan-results-v*.json) for documentation
5. Authority Attribution: Every claim must cite specific authority source (HikariCP docs, PostgreSQL guide, OWASP)

Common Tasks

Start a New Day

# 1. Read the plan
cat plan.md | grep "^### Day X"

# 2. Check current status
cat CHECKLIST.md | grep "^### Day X"

# 3. Verify environment
aphoria --version
curl http://localhost:18180/health

Verify Corpus Setup

# Count dbpool claims
curl 'http://localhost:18180/v1/aphoria/corpus?sources[]=vendor' | \
  jq '.items | map(select(.subject | startswith("dbpool"))) | length'

# Should return: 25-30 after Day 1

Check Violation Status

# Current violation count
aphoria scan --format json | jq '.findings | length'

# Breakdown by severity
aphoria scan --format json | \
  jq '.findings | group_by(.verdict) | map({verdict: .[0].verdict, count: length})'

Troubleshooting

Aphoria not found

cd /home/jml/Workspace/stemedb/applications/aphoria
cargo build --release
sudo cp target/release/aphoria /usr/local/bin/

Corpus empty after creating claims

# Verify API is using correct corpus DB
ps aux | grep stemedb-api
# Should show: STEMEDB_CORPUS_DB_DIR=/home/jml/.aphoria/corpus-db

# If not, restart API with correct env var

Scan finds no violations

# Enable debug logging
RUST_LOG=aphoria=debug aphoria scan

# Verify claims exist
curl 'http://localhost:18180/v1/aphoria/corpus?sources[]=vendor' | \
  jq '.items[] | select(.subject | contains("dbpool"))'

Documentation Requirements

All documentation must include:

• Before/After Evidence: Screenshots of violations → clean scans
• Cost Analysis: Estimated impact of prevented incidents ($50K connection exhaustion, 20 engineer-hours debugging)
• Metrics: Detection accuracy (100%), scan performance (≤0.3s), false positive rate (0%)
• Authority Attribution: Every claim linked to specific source (HikariCP wiki page, PostgreSQL docs, OWASP A07)

Related Documentation

• plan.md - Detailed 5-day implementation plan
• CHECKLIST.md - Execution checklist with templates and examples
• /home/jml/Workspace/stemedb/CLAUDE.md - Parent project guidance
• /home/jml/Workspace/stemedb/applications/aphoria/README.md - Aphoria documentation