Docs prompt for API with telemetry

api-docs-prompt

# Plan to implement

## Plan: Document Project Features under docs/features/

## Context

The api has 8 distinct components but no feature-level
documentation. The existing docs/learn/ teaches Go fundamentals. This new
docs/features/ will teach what each component does, why it exists, and how it
works in this codebase — aimed at a developer onboarding onto this project or
learning these infrastructure concepts for the first time.

Each component gets two documents:
- purpose.md — What it is and why it matters, explained through analogies to
sa  TypeScript/database/cloud equivalents
- functionality.md — How it's implemented in this codebase: concrete Go code,
  interfaces, wiring, best practice comparison


## Directory Structure

```
docs/features/
├── README.md # Index with category groupings

├── infrastructure/
│   ├── otel/
│   │   ├── purpose.md # OTel as the universal telemetry SDK
│   │   └── functionality.md # OtelService interface, gRPC exporter, noop pattern
│   ├── jaeger/
│   │   ├── purpose.md # Distributed tracing visualization
│   │   └── functionality.md # Docker setup, OTel Collector pipeline, trace flow
│   ├── prometheus/
│   │   ├── purpose.md # Metrics collection and querying
│   │   └── functionality.md # Scrape config, OTel Collector export, metric types
│   └── redis/
│       ├── purpose.md # In-memory data store
│       └── functionality.md # Client factory, OTel instrumentation, connection pooling

├── resilience/
│   └── circuit-breaker/
│       ├── purpose.md # Protecting services from cascading failures
│       └── functionality.md # Breaker interface, RedisBreaker, middleware integration

├── security/
│   └── cognito-auth/
│       ├── purpose.md # JWT authentication with AWS Cognito
│       └── functionality.md # JWKS caching, token validation, Fiber middleware

├── core/
│   ├── fiber/
│   │   ├── purpose.md # HTTP framework and middleware pipeline
│   │   └── functionality.md # App factory, middleware stack order, error handling
│   └── education-service/
│       ├── purpose.md # External API integration pattern
│       └── functionality.md # EducationService interface, OAuth2, HTTPTransport, Submit flow
```

**Total:** 17 files (1 README + 8 components × 2 docs each)


## Document Template

### purpose.md template

1. One-line summary — what it is
2. The Problem — what goes wrong without it
3. Analogy — map to TypeScript/DB/Cloud equivalent the reader already knows
4. How It Fits Here — one paragraph on its role in verification-service-api
5. Key Takeaway — single sentence


### functionality.md template

1. Architecture Snapshot — ASCII diagram of data/control flow
2. Key Files — table of files with one-line descriptions
3. Interfaces & Structs — annotated code blocks from the actual codebase
4. How It's Wired — trace from main.go through initialization
5. Connection Points — what other components it touches
6. Best Practice Comparison — current design vs. common patterns, strengths
   and gaps
7. Improvement Opportunities — concrete suggestions


## Key Source Files Referenced per Component

| Component | Primary Files |
|-----------|---------------|
| OTel | pkg/core/otel.go, pkg/core/oteltest.go, pkg/core/logger.go |
| Jaeger | docker-compose.yml, otel-collector-config.yml |
| Prometheus | prometheus.yml, otel-collector-config.yml, docker-compose.yml |
| Redis | pkg/redis/redis.go, pkg/redis/redis_test.go |
| Circuit Breaker | pkg/circuitbreaker/circuitbreaker.go, pkg/circuitbreaker/redis_breaker.go, api/middleware/middleware.go |
| Cognito Auth | api/middleware/middleware.go, pkg/core/model.go |
| Fiber | api/app.go, api/routes/router.go, api/routes/status_router.go |
| Education Service | pkg/education/service.go, pkg/education/oauth.go, pkg/education/submit.go, pkg/education/models*.go |


## Writing Guidelines

- Target length: purpose.md ~80-120 lines, functionality.md ~150-250 lines
- All code snippets reference actual files with file:line notation
- Analogies use TypeScript (Express/NestJS), PostgreSQL, or AWS services
- "Best practice comparison" is honest: praise good patterns, note gaps
  without sugar-coating
- Tone: direct, educational, assumes Go beginner but experienced in other
  stacks


## Execution Order

1. Create docs/features/README.md with full index
2. Infrastructure category (OTel → Jaeger → Prometheus → Redis) — these
   build on each other
3. Resilience category (Circuit Breaker) — depends on Redis understanding
4. Security category (Cognito Auth)
5. Core category (Fiber → Education Service) — ties everything together