issue-handler

1. •Andamio API Gateway: A unified gateway that consolidates all backend services
   • •Authentication and user management
   • •Course and Project data (merged on-chain + off-chain)
   • •Transaction building endpoints
   • •TX state machine (pending transaction tracking)
2. •Andamio T3 App Template: A reference implementation frontend for the Andamio API Gateway

It is still early in the development of each, and we expect to find errors. Your job is to process these errors and ensure they get to the teams who can fix them. </introduction>

Architecture (Unified Gateway)

All API calls now flow through the unified Andamio API Gateway:

Frontend (T3 Template)
    │
    ▼
/api/gateway/[...path] (Next.js proxy)
    │
    ▼
Andamio API Gateway (unified)
    ├── /api/v2/auth/*     → Authentication
    ├── /api/v2/course/*   → Course data (merged)
    ├── /api/v2/project/*  → Project data (merged)
    └── /api/v2/tx/*       → Transaction building

Local Repositories

Sibling repos are located at ../ relative to the current project:

Note: The gateway consolidates what was previously 3 separate APIs (DB API, TX API, Andamioscan). Issues should generally be routed to the gateway team first.

If you cannot find a sibling repo locally, ask the user: "Do you want to use local repos or GitHub issues?" </references>

Inputs

You will receive error logs from the user. These may be in any format:

• •GCP Cloud Logging output
• •Local terminal/stdout
• •Browser console errors
• •API response errors (from /api/gateway/* proxy)
• •Any other format the user can provide

Diagnostics

1. •Diagnose the root cause of each error
2. •Identify where the issue originates:
   • •Frontend (T3 Template): React components, hooks, client-side code
   • •Gateway API: Server-side errors, endpoint issues, validation
   • •Andamioscan: On-chain data indexing issues

Issue Flow

Issues should flow through the stack:

T3 App Template → Andamio API Gateway → Backend teams

Frontend issues: Fix directly in T3 Template API issues: Route to Gateway team (andamio-api repo) Indexing issues: Route through Gateway team (they coordinate with Andamioscan)

Rabbit Hole Mode

When the user says "rabbit hole mode", this means:

1. •Assume the API is complete and functional - Focus fixes on T3 App Template only
2. •Follow issues to their root cause - Don't just fix symptoms, find the underlying problem
3. •Search for similar patterns - After fixing one issue, grep/search for the same pattern elsewhere
4. •Fix all instances - Apply the fix consistently across the entire codebase

Rabbit Hole Workflow

Issue reported
    ↓
Diagnose root cause (not just symptoms)
    ↓
Fix the immediate issue
    ↓
Search: "Does this pattern exist elsewhere?"
    ↓
Fix ALL instances of the same pattern
    ↓
Verify build passes
    ↓
Update /project-manager STATUS.md
    ↓
Commit with detailed message

Example: TX Confirmation Bug (Session 28)

1. •Symptom: UI stuck on "Confirming on blockchain..."
2. •Root cause: useTxWatcher only treated "updated" as terminal, not "confirmed"
3. •Search: grep 'status.state === "updated"' → found 17 files with same pattern
4. •Fix all: Updated all 17 transaction components
5. •Verify: npm run build passes
6. •Document: Updated STATUS.md with full analysis

Key Search Patterns

When fixing a pattern, search for similar issues:

# Find all usages of a pattern
grep -r "pattern" src/components/

# Find all files using a hook
grep -l "useTxWatcher" src/

# Check generated types match API spec
curl -s "$GATEWAY_URL/api/v1/docs/doc.json" | jq '.definitions["TypeName"]'

Common Error Patterns

Outputs

For frontend issues (owned by T3 Template):

• •Diagnose and fix directly within the project

For backend issues (owned by Gateway): Prompt the user for their preferred handoff method:

1. •

   REPL Note: Log a formatted note that can be copied to another Claude Code session running in the target repo

2. •

   GitHub Issue: Use gh issue create to file an issue:

   bash

   gh issue create --repo Andamio-Platform/andamio-api --title "..." --body "..."
   

Issue Template

When routing to another repo, include:

## Error Summary
[One-line description]

## Error Details
[Full error message/stack trace]

## Reproduction Steps
1. [Step 1]
2. [Step 2]
3. [Expected vs actual]

## Environment
- T3 Template branch: [branch]
- Gateway URL: [url]
- Network: preprod/mainnet

## Diagnosis
[Your analysis of the root cause]