docs: add technical debt audit

doc/technical_debt_audit.md

@@ -0,0 +1,37 @@
+# Technical Debt Audit - Edtech Platform
+
+**Date:** April 30, 2026  
+**Status:** Post-Stabilization (v1.0)
+
+## 1. Architecture & Orchestration
+| Issue | Severity | Impact | Recommendation |
+|-------|----------|--------|----------------|
+| Parallel Process Management | High | Reliability | Replace `start.sh` with a process manager like PM2 to handle crashes independently. |
+| BullBoard Disabled | Medium | Monitoring | Re-enable BullBoard in `internal.ts` once route stability is confirmed. |
+| Single Container for API/Worker | Medium | Scaling | Eventually separate API and Worker into two different Railway services for better horizontal scaling. |
+
+## 2. Multi-Tenancy & Security
+| Issue | Severity | Impact | Recommendation |
+|-------|----------|--------|----------------|
+| Global API Keys | Medium | Isolation | Fully migrate all AI/Payment providers to use organization-specific encrypted secrets from the database. |
+| Webhook Header Validation | Medium | Security | Ensure HMAC signature verification is active and enforced on all Meta/Stripe webhooks. |
+| Cache Invalidation | Low | Consistency | Implement Redis pub/sub for organization secret cache invalidation across replicas. |
+
+## 3. Code Quality & Maintenance
+| Issue | Severity | Impact | Recommendation |
+|-------|----------|--------|----------------|
+| Lack of Automated Tests | High | Speed | Implement Jest/Vitest for critical pedagogical logic and organization isolation. |
+| TypeScript "any" usage | Low | Safety | Clean up `as any` casts in `index.ts` and `internal.ts` by refining Fastify type augmentations. |
+| Documentation Gaps | Medium | Onboarding | Document the multi-tenant R2 storage structure and the personality configuration JSON schema. |
+
+## 4. Infrastructure & DevOps
+| Issue | Severity | Impact | Recommendation |
+|-------|----------|--------|----------------|
+| /tmp Disk Management | Low | Stability | Enhance the cleanup service to respect per-tenant storage quotas. |
+| Centralized Logging | Medium | Debugging | Integrate a logging provider (Logtail, Datadog) to aggregate logs from multiple processes. |
+| Environment Variable Sync | Low | Deploy | Keep `.env.example` strictly synchronized with Railway production variables. |
+
+---
+
+## Conclusion
+The platform is currently **Production-Ready** for initial launch. The stabilization phase has resolved critical boot failures and port conflicts. The next phase should focus on **Observability** (Re-enabling BullBoard) and **Test Coverage**.