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#
- No retry/resilience patterns
- No request interceptors
- No WebSocket support
- No streaming (SSE)
- No batch operations
- No type guards for runtime validation
- No SDK-level caching
- 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