docs/reference/INTEGRATION_INVENTORY.md

Integration Inventory

Nguồn audit: AutoCode Video codex/hf-prod-sync tại commit 595ccdfaf45ff83473f2da8fd2c71d491828e5f5. Tổng cộng xác định 16 integration hoặc nhóm integration có boundary riêng.

Cột trạng thái cuối là implementation status quan sát trong source, độc lập với verification status. Cả 16 integration đều SOURCE_VERIFIED và NOT_RUNTIME_VERIFIED trong Phase 0; không integration nào được nâng lên RUNTIME_VERIFIED hoặc PARTIAL_RUNTIME_EVIDENCE. Vì vậy các từ “Active”, “đầy đủ” hoặc “production choice” bên dưới chỉ mô tả source-level wiring. Ma trận chuẩn cho Google OAuth, GitHub OAuth, LLM generation, Omnivoice, HyperFrames preview, Modal, HF storage delivery, social, Cloudflare, AI asset analysis và vision QA nằm tại CURRENT_SYSTEM_MAP.md.

ID	Integration	Mục đích và điểm gọi	Secret/cấu hình	Timeout và retry quan sát được	Failure mode	MVP Oloka	Implementation status và source evidence
INT-01	HyperFrames CLI	Preview, check, render composition; spawn từ preview manager, quality service và render provider	Version package, Chromium path, project hyperframes.json	Preview chờ readiness khoảng 4,5 giây; local render không có timeout cấp provider rõ ràng	CLI/browser lỗi, composition contract sai, child process treo, preview port/process mất khi restart	Bắt buộc	Active; package.json, server.js, services/processRunner.js, services/renderProviders.js
INT-02	HyperFrames Registry	Discover/materialize block/component được composition tham chiếu	Registry URL trong project config; cache/local package	Có validation trước TTS và render; timeout mạng phụ thuộc CLI/fetch; unresolved block là fatal	Block thiếu/rỗng, path escape, version drift, nested composition chưa materialize	Bắt buộc nếu dùng registry	Active nhưng phức tạp; services/templateRegistryService.js, services/forgePipelineService.js, routes/render.js, tests/forgePreTtsRegistryMaterialization.test.js
INT-03	OpenAI-compatible LLM	Planning, prompt/composition generation, edit, BGM director và repair	Base URL, API key, model, reasoning effort	Undici dispatcher: connect 30 giây, header/body 10 phút; streaming có fallback non-stream; retry policy khác nhau theo call site	Timeout dài, JSON rỗng/sai schema, model không hỗ trợ field, token/cost tăng, retry sinh kết quả khác	Bắt buộc	Active; server.js, services/llmStreamingService.js, services/forgeLlmService.js, services/forgePipelineService.js
INT-04	Image/audio/video recognition endpoints	Phân tích asset, embedding/search, vision QA; dùng giao thức OpenAI-compatible	Có thể inherit LLM config hoặc dùng key/model riêng	Asset analysis tự retry một lần sau khoảng 2 giây; một số call không có AbortSignal rõ ràng	Metadata fallback/mock, pending bị kẹt, embedding thiếu, provider trả format lạ	Hậu MVP; MVP chỉ cần metadata kỹ thuật	Partial; services/assetAnalysisService.js, services/assetSearch.js, services/videoQualityService.js, routes/assets.js
INT-05	Omnivoice Gateway	Tạo narration theo scene, poll job, tải audio và alignment	Base URL, bearer token, voice ID, speed/steps	Poll mặc định 2 giây; HTTP retry tối đa 6 lần, exponential/jitter tối đa 120 giây; job recovery có delay 15 giây	Cold start, 401, 429/5xx, invalid JSON, job failed/treo, audio/alignment thiếu, copy mount lỗi	Bắt buộc cho MVP có voice	Active và có resilience; services/omnivoiceAuth.js, services/omnivoiceSceneTts.js, routes/tts.js
INT-06	Local transcription tool	Tạo word timing khi TTS alignment không đủ	Python/media tool runtime, ffmpeg	Process timeout do call site/tool; prompt asset subprocess có timeout riêng, transcription retry không thống nhất	Runtime/model không cài, CPU/memory cao, encoding/path Windows khác hosted	Không bắt buộc nếu TTS luôn trả alignment	Active fallback; services/ttsMediaService.js, routes/compile.js, services/forgePipelineService.js, scripts/setup-local.*
INT-07	OpenAI audio transcription fallback	Fallback transcript khi local transcription thất bại	OpenAI-compatible base URL + API key	Download/provider call có timeout khoảng 30 giây ở media service; không thấy retry thống nhất	File lớn, endpoint không hỗ trợ multipart transcription, timeout/quota	Hậu MVP	Partial fallback; services/ttsMediaService.js, routes/compile.js, services/forgePipelineService.js
INT-08	Modal renderer	Nhận bundle, chạy HyperFrames từ xa, lưu/tải MP4	MODAL_RENDER_BASE_URL, API token, resource preset; Modal secret/volume	Request 60 giây; poll 2 giây; tổng 15 phút ở client, function 30 phút; 3 retry với exponential backoff	Bundle > giới hạn, base64/memory cao, 401, queue/remote failure, timeout, output URL thiếu, version CLI drift	Bắt buộc cho hosted MVP hoặc thay bằng provider tương đương	Active production choice; services/renderProviders.js, deploy/modal-renderer/app.py, Dockerfile, routes/status.js
INT-09	Hugging Face Docker Space	Host frontend + API all-in-one	HF Space, HF_TOKEN cho deploy, env/secrets runtime	GitHub workflow chạy test rồi force-with-lease; restart Space nếu paused; không chờ chứng minh app READY/served bundle	Build/start chậm, /data mount lỗi, runtime SHA khác source, cold start, deployment drift	Bắt buộc cho môi trường hiện tại	Active; .github/workflows/deploy-hf-space.yml, Dockerfile, README.md
INT-10	Hugging Face persistent storage / S3 Gateway	Lưu /data; giao MP4 qua signed S3 URL thay vì stream qua app	Namespace, bucket, S3 access key/secret	Signed URL 1 giờ, refresh buffer 5 phút; không có retry upload vì app giả định mount là nguồn bytes	Credential thiếu thì fallback mount; object chưa sync/không tồn tại; signed URL cache stale; permission	Bắt buộc cho durability/delivery hiện tại	Active delivery, upload implicit qua mount; services/hfBucketDelivery.js, routes/media.js, services/videoDelivery.js, README.md
INT-11	Google OAuth	Hosted login chính	Client ID/secret, callback URL	Không thấy timeout/retry explicit cho token/profile request	State/callback sai, token exchange/profile lỗi, email không có, user pending/disabled	Bắt buộc nếu giữ Google-only login	Active UI; auth.js, services/oauthGoogleParams.js, public/index.html, public/landing.js
INT-12	GitHub OAuth	Alternative login	Client ID/secret, callback URL	Không thấy timeout/retry explicit	Email private/không có, callback về entry khác Google, không có nút UI chính	Không cần MVP	Implementation có nhưng consumer không rõ; auth.js, public/index.html
INT-13	TikTok Content Posting API	Publish project MP4	User access token, privacy/interaction flags	Không thấy timeout/retry/poll durable	Init/upload thành công nhưng publish vẫn xử lý; token/scope/quota; file/range upload lỗi	Hậu MVP	Partial; routes/socialPublish.js, public/app.js, services/sharedConfig.js
INT-14	YouTube Data API upload	Upload video và trả watch URL	OAuth access token, category, privacy	Không thấy timeout/retry/resumable recovery cấp app	Token hết hạn, scope thiếu, upload session lỗi, quota	Hậu MVP	Partial; routes/socialPublish.js, public/app.js
INT-15	Facebook Graph Video API	Upload MP4 lên Page	Page ID, Page token, Graph version	Không thấy timeout/retry	Token/page permission/version lỗi, upload dài, response partial	Hậu MVP	Partial; routes/socialPublish.js, public/app.js
INT-16	Cloudflare frontend/backend/R2/D1	Alternate static frontend, Worker backend và migration project	Wrangler auth, internal API token, R2 bucket, D1 name, backend origin	Smoke/preflight retry 401/503 tối đa 8 lần, 1,5 giây; deploy qua Wrangler	Source/config deploy/cloudflare-* không có trong snapshot; smoke contract khác Express; migration có hai data models	Không đưa vào MVP	Legacy/incomplete; package.json, scripts/build-cloudflare-frontend.mjs, scripts/preflight-cloudflare-backend.mjs, scripts/smoke-cloudflare-backend.mjs, scripts/migrate-projects-to-cloudflare.mjs

Nguồn media web bổ trợ

Ngoài 16 boundary trên, pipeline còn có hành vi capture URL, tải media và tìm ảnh qua website/DuckDuckGo/Unsplash. Đây là capability phụ nằm trong prompt asset service, không nên coi là storage provider. Các request có timeout ngắn khoảng 3–15 giây nhưng phụ thuộc mạnh vào CORS, anti-bot, redirects, content type và bản quyền nguồn.

Bằng chứng: services/promptAssetService.js, services/urlDetection.js, routes/generate.js.

Đề xuất: tắt trong MVP mặc định; chỉ bật qua một media ingestion service có allowlist, attribution/licensing metadata, size limit và SSRF protection.

Nhận xét cross-integration

1. Cấu hình phân tán: env, SQLite shared settings và localStorage cùng quyết định provider. Bằng chứng: services/sharedConfig.js, public/app.js, Dockerfile.
2. Retry không thống nhất: TTS và Modal có policy rõ, LLM/recognition/social/OAuth không dùng một client chung. Bằng chứng: services/omnivoiceSceneTts.js, services/renderProviders.js, services/llmStreamingService.js, routes/socialPublish.js.
3. Secret boundary yếu: hosted che secret khi trả response nhưng vẫn lưu plaintext; local browser giữ key. Bằng chứng: services/sharedConfig.js, public/app.js.
4. Version coupling: HyperFrames version phải tương thích giữa Node app, registry và Modal image. Bằng chứng: package.json, deploy/modal-renderer/app.py, Dockerfile.
5. Không có durable integration job: social publish và một số analysis chạy trực tiếp trong HTTP request hoặc background RAM. Bằng chứng: routes/socialPublish.js, services/assetAnalysisService.js.

Integration tối thiểu đề xuất cho Oloka MVP

• HyperFrames CLI/registry với version pin và preflight.
• Một OpenAI-compatible LLM provider qua adapter có schema validation/idempotency.
• Omnivoice hoặc một TTS adapter duy nhất có alignment.
• Một hosted render provider (Modal hiện tại có thể là implementation đầu tiên sau interface).
• HF Space + durable object storage cho môi trường hiện tại.
• Google OAuth nếu sản phẩm vẫn đóng quyền truy cập.

Recognition nâng cao, web scraping, GitHub OAuth, social publishing và Cloudflare alternate topology nên để hậu MVP.