# 25.1.3-5 — TypeScript SDK, Infrastructure, Test Suite

> Source: `oshun/minerva/{sdk,infrastructure,docker,k8s,tests}/` Analysis date:
> 2026-02-28

---

## 1. TypeScript SDK (87 source files)

### Structure

```
sdk/typescript/src/
├── index.ts          # Barrel exports
├── runtime.ts        # HTTP client (14.5KB)
├── apis/             # 11 API client classes
│   ├── AuthenticationApi.ts
│   ├── CoursesApi.ts
│   ├── GenerationApi.ts
│   ├── AITutoringApi.ts
│   ├── StudentProgressApi.ts
│   ├── AssessmentsApi.ts
│   ├── KnowledgeGraphApi.ts
│   ├── MultimediaApi.ts
│   ├── AnalyticsApi.ts
│   ├── SystemApi.ts
│   └── UsersApi.ts
└── models/           # 75 TypeScript types
```

### Generation

- **100% auto-generated** via OpenAPI Generator v7.17.0
- **Generator:** TypeScriptFetchClientCodegen
- **Source:** OpenAPI spec from FastAPI backend
- **Build:** ESM + CJS modules

### 75 Existing TypeScript Types

Core: Course, Topic, SubTopic, Lesson, Section Assessment: Quiz, QuizQuestion,
AssessmentAttempt, AttemptResult Learning: StudentProgress, CourseProgress,
LessonProgress Tutoring: TutoringSession, TutoringMessage, HintResponse
Multimedia: Diagram, AudioSegment, Presentation, PresentationSlide Graph:
GraphNode, GraphEdge, KnowledgeGraphResponse Requests/Responses: APIResponse,
ErrorResponse, PaginatedResponse, JobResponse

### What's Missing

1. No retry/resilience patterns
2. No request interceptors
3. No WebSocket support
4. No streaming (SSE)
5. No batch operations
6. No type guards for runtime validation
7. No SDK-level caching
8. Zero custom helpers

### Assessment

Minimal but functional OpenAPI client. Needs significant enhancement for
@metis/api-client: retries, timeouts, WebSocket, caching, observability.

---

## 2. Infrastructure

### Docker Compose Services

| Service        | Image                | Ports       | Purpose            |
| -------------- | -------------------- | ----------- | ------------------ |
| neo4j          | neo4j:5.13-community | 7474, 7687  | Graph database     |
| mongodb        | mongo:7.0            | 27017       | Document storage   |
| weaviate       | weaviate:1.23.7      | 8080, 50051 | Vector search      |
| redis          | redis:7.2-alpine     | 6379        | Cache/sessions     |
| chatterbox-tts | custom               | 8000        | TTS (dev only)     |
| minerva-api    | custom               | 8001        | FastAPI (dev only) |

### AWS CDK Stacks (11 modules)

| Stack                  | Size   | Purpose                                       |
| ---------------------- | ------ | --------------------------------------------- |
| network.py             | 5.8KB  | VPC, subnets, NAT (1/2/3 per env)             |
| security.py            | 19.1KB | Secrets Manager, IAM roles, policies          |
| storage.py             | 16.2KB | S3 buckets, ECR repos, lifecycle              |
| compute.py             | 19.5KB | ECS Fargate (API 2-4 tasks, Worker 1-8 tasks) |
| redis.py               | 11.9KB | ElastiCache Redis 7.x, multi-AZ               |
| observability.py       | 13.6KB | CloudWatch, dashboards, alarms                |
| scaling.py             | 14.4KB | Target tracking (CPU 70%, Memory 80%)         |
| scheduler.py           | 9.2KB  | EventBridge cron, batch jobs                  |
| global_distribution.py | 8.8KB  | CloudFront CDN                                |
| storage_replica.py     | 6.4KB  | S3 cross-region replication                   |

### Deployment Sizing

| Component          | Dev                          | Prod                         |
| ------------------ | ---------------------------- | ---------------------------- |
| API ECS            | 2-4 tasks, 1024 CPU, 2GB RAM | 4-8 tasks, 2048 CPU, 4GB RAM |
| Worker ECS         | 1-8 tasks, 2048 CPU, 4GB RAM | 4-8 tasks, 4096 CPU, 8GB RAM |
| NAT Gateways       | 1                            | 3                            |
| Availability Zones | 1                            | 3                            |

### Database Migrations

- **Alembic** configured but only baseline migration exists
- Schema managed at **runtime** (schema-on-read)
- **Missing:** Versioned schema history, rollback, audit trail

### Debt to Discard

- Hardcoded passwords in docker-compose
- Weaviate anonymous access (no auth)
- Neo4j + Weaviate (migrate to PostgreSQL + pgvector)
- No proper schema migrations

---

## 3. Test Suite

### Scale

- **1,822 test files** across 81 categories
- **Estimated 5,000+ test functions**
- **70% unit / 20% integration / 10% e2e**

### Largest Categories

| Category      | Files | Focus                          |
| ------------- | ----- | ------------------------------ |
| content       | 84    | Content generation, validation |
| cli           | 65    | CLI commands, config           |
| linters       | 64    | Quality linters (20+ types)    |
| course        | 62    | Course CRUD, import/export     |
| accessibility | 56    | WCAG compliance                |
| api           | 52    | REST endpoints, auth           |
| observability | 44    | Logging, metrics               |
| agents        | 32    | LLM agent behaviors            |
| vlm           | 27    | Vision-language models         |
| prompts       | 25    | Prompt engineering             |
| learning      | 25    | Learning paths                 |
| database      | 25    | DB backends                    |
| verification  | 24    | Fact-checking                  |
| security      | 24    | Auth, permissions              |

### Test Infrastructure

- **Framework:** pytest 7.0+
- **Async:** pytest-asyncio
- **Mocking:** pytest-mock
- **Coverage:** pytest-cov
- **Parallel:** pytest-xdist
- **Performance:** pytest-benchmark
- **Retry:** pytest-rerunfailures

### Fixture Library

```
tests/fixtures/
├── environment_isolation.py    # Temp DB schemas, isolated FS
├── db_seeding.py               # Pre-loaded courses, users
├── data_validation.py          # Constraint checks
├── e2e_fixtures.py             # Full course instances
├── model_fixtures.py           # Mock LLM responses
├── data_backup_restore.py      # Backup/restore testing
├── idempotency_fixtures.py     # Idempotent operation testing
└── data_versioning.py          # Version tracking
```

### Mock Patterns

- Mock LLM providers (ChatGPT, Claude, Gemini)
- Mock database backends (MongoDB, Neo4j)
- Mock multimedia services (TTS, image gen)
- Mock file storage (S3)

### Coverage

- Estimated 60-70% based on `sample_coverage.json` (794KB)
- No active CI/CD enforcement found
- Gaps: error paths, async cleanup, security checks
