Eve library

25.1.3-5 — TypeScript SDK, Infrastructure, Test Suite

Guide

Revision 1

On this page

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


1. TypeScript SDK (87 source files)#

Structure#

text
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#

text
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