Spaces:
Sleeping
Sleeping
| # 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. | |