AI Creator Studio Telegram

# AI Creator Studio Telegram Blueprint

Dokumen ini adalah blueprint product, UX, arsitektur, dan roadmap untuk membangun AI Creator Studio berbasis Telegram dengan Hermes Agent sebagai autonomous agent utama.

Target deployment wajib:

```text
root@187.77.119.32:"/root/hermes-projects/AI Creator Studio Telegram"
```

Catatan operasional: karena nama folder mengandung spasi, semua command shell harus memakai quote. Untuk nama service, package, queue, container, database, dan metric gunakan slug stabil `ai-creator-studio-telegram`.

## 1. Product Requirement Document

### Ringkasan Produk

AI Creator Studio Telegram adalah platform AI creator premium yang berjalan langsung di Telegram. Platform ini membantu user membuat image/video berkualitas tinggi melalui conversational UI, preset kreatif, form interaktif, prompt intelligence, project history, credit/token dashboard, dan workflow generation multi-provider.

Hermes Agent tetap menjadi agent autonomous penuh. Codex/Antigravity hanya dipakai sebagai reasoning layer untuk membantu analisis, planning, arsitektur, dan validasi keputusan, bukan mengganti workflow Hermes.

### Problem Statement

Creator, marketer, UMKM, agency, dan brand owner membutuhkan cara cepat membuat visual profesional tanpa berpindah antar banyak aplikasi AI. Kebanyakan tool premium memiliki UI kompleks, biaya tidak transparan, dan workflow project/history sulit dipantau. Telegram dapat menjadi studio cepat yang terasa seperti aplikasi premium jika bot menyediakan menu, form, progress, result card, quick action, dan dashboard resource yang jelas.

### Goals

- Menyediakan pengalaman AI Creator Studio premium langsung di Telegram.
- Memungkinkan text/image/video generation melalui workflow yang dipilih otomatis oleh Hermes.
- Mengubah prompt sederhana menjadi prompt profesional yang siap dipakai provider.
- Menyediakan project management: history, favorite, duplicate, regenerate, export prompt, download result.
- Menampilkan credit/token/usage/queue/storage secara transparan sebelum dan sesudah generation.
- Mendukung multi-provider AI melalui adapter yang mudah ditambah.
- Membangun sistem production-ready, secure, scalable, observable, dan maintainable.

### Non-Goals Fase Awal

- Tidak membangun marketplace publik di fase MVP.
- Tidak menyediakan editor video timeline penuh seperti desktop NLE.
- Tidak menyimpan secret provider di database plaintext.
- Tidak membuat Hermes hanya menjadi executor pasif.

### Target User

- Creator social media yang butuh output cepat untuk Reels/TikTok/Shorts.
- Marketer dan agency yang membuat campaign visual.
- Brand owner/UMKM yang butuh product ads.
- Content strategist yang perlu banyak variasi prompt/output.
- Admin/operator yang memantau quota, job, dan provider.

### Scope MVP

- Telegram bot dengan menu utama dan command `/start`, `/token`, `/usage`, `/projects`, `/settings`.
- Image Studio: text-to-image, image-to-image, upscale, enhancement.
- Video Studio: text-to-video, image-to-video, video enhancement.
- Prompt Intelligence untuk enhancement prompt dan parameter planning.
- Project Library dengan history, favorite, duplicate, regenerate, export prompt, download.
- Credit dashboard dan estimasi resource sebelum generation.
- Provider abstraction dengan minimal mock provider + adapter placeholder untuk provider real.
- Queue worker untuk job asynchronous.
- PostgreSQL, Redis, object storage S3-compatible, logging, healthcheck.

### Scope V1

- Background removal/replacement, style transfer, frame interpolation, motion enhancement.
- Multi-provider routing berbasis capability, cost, quota, quality, dan rate limit.
- Admin dashboard web internal.
- Billing/top-up/manual credit adjustment.
- Moderation, safety classification, dan abuse detection.
- SLA-aware retry dan fallback provider.

### Success Metrics

- Generation completion rate minimal 95% untuk job yang valid.
- Median interaction-to-queue time kurang dari 3 detik.
- User dapat melihat estimasi resource sebelum generation dalam setiap workflow berbayar.
- Project result tersimpan dan dapat diakses ulang.
- Provider failure dapat ditangani dengan retry/fallback tanpa kehilangan project state.
- Tidak ada secret yang tersimpan di code repository.

## 2. Product Vision

AI Creator Studio Telegram harus terasa seperti studio kreatif premium yang ringkas, bukan chatbot biasa. User memilih mode, mengisi detail melalui multi-step form, melihat preview prompt/parameter/resource, lalu Hermes Agent menjalankan generation secara autonomous: menganalisis intent, menyusun workflow, memilih provider, menjalankan queue, memvalidasi hasil, menyimpan project, dan mengirim result card.

Prinsip produk:

- `Agent-first`: Hermes berpikir dan mengambil keputusan workflow, bukan hanya meneruskan prompt.
- `Transparent cost`: resource estimate ditampilkan sebelum generation.
- `Reusable creative system`: preset, prompt, parameter, dan project dapat dipakai ulang.
- `Provider-agnostic`: provider bisa diganti atau ditambah tanpa mengubah UX utama.
- `Production-grade`: setiap job punya status, audit log, retry, error handling, dan storage lifecycle.

Positioning:

```text
Premium AI Creator Studio inside Telegram for cinematic image and video generation.
```

## 3. User Persona

### Persona 1: Social Media Creator

- Tujuan: membuat konten visual cepat untuk Reels/TikTok/Shorts.
- Kebutuhan: preset 9:16, prompt enhancement, result cepat, regenerate.
- Pain point: tidak mahir prompt engineering, sering coba banyak tool.
- Fitur penting: Social Media Reel, UGC, Action Scene, Project Library.

### Persona 2: Performance Marketer

- Tujuan: membuat product ads dan commercial visuals.
- Kebutuhan: brand consistency, product-focused prompt, export prompt, duplicate project.
- Pain point: output tidak konsisten dan biaya tidak transparan.
- Fitur penting: Product Ads, Commercial Ads, Luxury Brand, usage dashboard.

### Persona 3: Agency Creative Lead

- Tujuan: membuat banyak konsep visual untuk client.
- Kebutuhan: project history, favorite, prompt versioning, high quality.
- Pain point: tracking versi prompt dan hasil sulit.
- Fitur penting: Project Library, favorites, regenerate, team/admin roadmap.

### Persona 4: Admin/Operator

- Tujuan: memantau queue, credits, quota provider, dan service health.
- Kebutuhan: dashboard resource, alert, error log, rate limit tracking.
- Pain point: provider quota habis tanpa terdeteksi.
- Fitur penting: credit provider sync, job monitor, audit log, alerts.

## 4. Use Case Diagram

```mermaid
flowchart LR
  User((Telegram User))
  Admin((Admin))
  Bot[Telegram Bot UI]
  Hermes[Hermes Agent]
  Studio[Creator Studio Workflows]
  Provider[AI Providers]
  Storage[Object Storage]
  Billing[Credits & Tokens]
  Project[Project Library]
  Queue[Queue Workers]
  Dashboard[Admin Dashboard]

  User --> Bot
  Admin --> Dashboard
  Bot --> Hermes
  Hermes --> Studio
  Studio --> Queue
  Queue --> Provider
  Queue --> Storage
  Queue --> Billing
  Queue --> Project
  Bot --> Project
  Bot --> Billing
  Dashboard --> Queue
  Dashboard --> Billing
  Dashboard --> Provider
```

Primary use cases:

- User membuat image dari text.
- User membuat video dari text atau image.
- User meningkatkan media existing.
- Hermes mengubah prompt sederhana menjadi prompt profesional.
- Hermes memilih provider/model/workflow terbaik.
- Sistem mengestimasi resource sebelum generation.
- Sistem menjalankan job asynchronous dan mengirim progress.
- User menyimpan, favorite, duplicate, regenerate, export prompt, download result.
- Admin memantau provider quota, queue, error, storage, dan usage.

## 5. User Flow

### General Generation Flow

```mermaid
sequenceDiagram
  participant U as User
  participant T as Telegram Bot
  participant H as Hermes Agent
  participant Q as Queue
  participant P as Provider
  participant S as Storage
  participant DB as Database

  U->>T: Select studio/menu
  T->>U: Multi-step form
  U->>T: Prompt/media/settings
  T->>H: Intent + context + user profile
  H->>H: Requirement analysis
  H->>H: Prompt enhancement
  H->>H: Workflow planning
  H->>H: Provider/model selection
  H->>T: Preview + resource estimate
  T->>U: Confirmation screen
  U->>T: Confirm generation
  T->>DB: Create project + job
  T->>Q: Enqueue generation job
  Q->>P: Run generation
  Q->>S: Store output
  Q->>DB: Save result + usage
  Q->>T: Job completed
  T->>U: Result card + quick actions
```

### Image Studio Flow

1. User pilih `Image Studio`.
2. Bot menampilkan mode: Text to Image, Image to Image, Upscale, Remove BG, Replace BG, Style Transfer, Enhance.
3. User memasukkan prompt/media.
4. User memilih preset, aspect ratio, resolution, quality.
5. Hermes menganalisis intent dan meningkatkan prompt.
6. Bot menampilkan preview prompt, parameter, estimasi credits/tokens/storage.
7. User confirm.
8. Sistem menjalankan job, tracking progress, validasi result, simpan project.
9. Bot mengirim result card dengan quick action.

### Video Studio Flow

1. User pilih `Video Studio`.
2. Bot menampilkan mode: Text to Video, Image to Video, Enhance, Upscale, Interpolation, Motion Enhancement.
3. User mengirim prompt/media dan memilih duration, resolution, fps, quality.
4. Hermes membuat shot plan, motion plan, camera movement, quality settings.
5. Bot menampilkan preview workflow dan estimasi resource.
6. User confirm.
7. Job masuk queue video priority.
8. Worker menjalankan provider, polling status, menyimpan result.
9. Bot mengirim video/result card.

## 6. Telegram UX Flow

### Main Menu

```text
🎨 Image Studio
🎬 Video Studio
🖼️ Image to Video
✨ Enhance Media
📂 My Projects
📊 Credits Dashboard
⚙️ Settings
```

### Command

| Command | Fungsi |
|---|---|
| `/start` | Menampilkan onboarding singkat dan main menu |
| `/token` | Menampilkan available credits, tokens, balance, active jobs |
| `/usage` | Menampilkan usage today, month, quota, storage |
| `/projects` | Membuka project library |
| `/settings` | Mengatur default preset, quality, language, notification |
| `/help` | Bantuan singkat dan support |

### Screen: Main Menu

```text
AI Creator Studio

Create cinematic images and videos with Hermes Agent.

Credits: 1,250
Active Jobs: 2
Queue: Normal

[🎨 Image Studio] [🎬 Video Studio]
[🖼️ Image to Video] [✨ Enhance Media]
[📂 My Projects] [📊 Credits]
[⚙️ Settings]
```

### Screen: Prompt Preview

```text
Prompt Preview

Mode: Text to Video
Preset: Cinematic
Aspect: 9:16
Duration: 8s
Resolution: 1080p
FPS: 24
Quality: High

Enhanced Prompt:
...

Estimated Usage:
Credits: 120
Tokens: 2,400
Storage: ~35 MB
ETA: 2-6 min

[✅ Generate] [✏️ Edit Prompt]
[⚙️ Change Settings] [❌ Cancel]
```

### Screen: Progress Tracking

```text
Generating Video

Status: Rendering
Progress: 62%
Provider: Auto-selected
Queue Position: 1
Elapsed: 02:14
ETA: 01:40

[🔄 Refresh] [📂 Open Project]
```

### Screen: Result Card

```text
Generation Complete

Project: Cinematic product reel
Used: 118 credits, 2,310 tokens
Output: 1080p, 8s, 24 FPS

[⬇️ Download] [🔁 Regenerate]
[⭐ Favorite] [📋 Export Prompt]
[🧬 Duplicate] [📂 Library]
```

### Multi-Step Form Pattern

- Step 1: pilih studio/mode.
- Step 2: kirim prompt/media.
- Step 3: pilih preset.
- Step 4: pilih aspect/resolution/quality.
- Step 5: Hermes preview.
- Step 6: confirm generation.
- Step 7: progress/result.

UX states wajib:

- Loading state saat Hermes menganalisis prompt.
- Empty state untuk project library kosong.
- Error state untuk provider gagal/rate limit.
- Success state setelah result tersimpan.
- Retry action jika failure recoverable.

## 7. System Architecture

### Recommended Stack

- Bot/API: Node.js + TypeScript.
- Telegram framework: grammY atau Telegraf.
- API framework: Fastify atau NestJS ringan.
- Queue: Redis + BullMQ.
- Database: PostgreSQL + Prisma.
- Storage: S3-compatible object storage, contoh Cloudflare R2, MinIO, AWS S3.
- Cache/rate-limit: Redis.
- Admin dashboard: Next.js App Router + TypeScript + Tailwind CSS.
- Observability: structured logs, OpenTelemetry-ready, healthcheck, metrics endpoint.
- Deployment: systemd atau Docker Compose di VPS.

Alasan stack: TypeScript menjaga typing end-to-end untuk bot, service, provider adapter, dan dashboard. PostgreSQL cocok untuk project/job/usage ledger. Redis/BullMQ cocok untuk job async image/video. S3-compatible storage menjaga output besar tidak membebani filesystem lokal.

### High-Level Architecture

```mermaid
flowchart TB
  Telegram[Telegram User/Bot API]
  Bot[Telegram Bot Service]
  API[Internal API Service]
  Hermes[Hermes Agent Orchestrator]
  Prompt[Prompt Intelligence Service]
  Workflow[Workflow Planner]
  Router[Provider Router]
  Queue[Redis BullMQ Queues]
  ImageWorker[Image Worker]
  VideoWorker[Video Worker]
  ProviderAdapters[Provider Adapters]
  DB[(PostgreSQL)]
  Redis[(Redis)]
  Storage[(S3 Object Storage)]
  Admin[Next.js Admin Dashboard]
  Metrics[Logs/Metrics/Alerts]

  Telegram <--> Bot
  Bot --> API
  API --> Hermes
  Hermes --> Prompt
  Hermes --> Workflow
  Workflow --> Router
  Router --> Queue
  Queue --> ImageWorker
  Queue --> VideoWorker
  ImageWorker --> ProviderAdapters
  VideoWorker --> ProviderAdapters
  ProviderAdapters --> Storage
  API --> DB
  Queue --> Redis
  ImageWorker --> DB
  VideoWorker --> DB
  Admin --> API
  Bot --> Metrics
  API --> Metrics
  ImageWorker --> Metrics
  VideoWorker --> Metrics
```

### Service Boundaries

| Service | Tanggung Jawab |
|---|---|
| `bot` | Telegram commands, inline keyboard, form state, delivery |
| `api` | Internal REST API, auth, project/job/usage endpoints |
| `agent` | Hermes orchestration, intent analysis, planning, validation |
| `workers` | Execute image/video jobs, provider polling, retry, storage |
| `admin-web` | Monitoring usage, provider quota, job queue, user/project |
| `provider-adapters` | Abstraction untuk provider image/video/enhancement |

### Provider Abstraction

Setiap provider adapter harus implement interface:

```ts
type ProviderCapability =
  | "text_to_image"
  | "image_to_image"
  | "upscale_image"
  | "remove_background"
  | "replace_background"
  | "style_transfer"
  | "enhance_image"
  | "text_to_video"
  | "image_to_video"
  | "enhance_video"
  | "upscale_video"
  | "frame_interpolation"
  | "motion_enhancement";

interface ProviderAdapter {
  id: string;
  displayName: string;
  capabilities: ProviderCapability[];
  estimate(input: GenerationRequest): Promise<ResourceEstimate>;
  generate(input: GenerationRequest): Promise<ProviderJobResult>;
  getJobStatus(providerJobId: string): Promise<ProviderJobStatus>;
  getBalance(): Promise<ProviderBalance>;
  getRateLimit(): Promise<ProviderRateLimit>;
}
```

## 8. Agent Workflow

Hermes Agent wajib tetap autonomous. Ia bukan executor pasif dan tidak hanya meneruskan command. Hermes mengelola seluruh lifecycle kreatif dan teknis.

### Agent Responsibilities

- Requirement analysis dari prompt/media/settings user.
- Intent detection: image, video, enhancement, ads, cinematic, social.
- Prompt enhancement dengan struktur profesional.
- Workflow planning berdasarkan intent, preset, output target, dan resource.
- Provider/model selection berdasarkan capability, quality, quota, cost, latency.
- Resource estimation sebelum job dimulai.
- Execution orchestration melalui queue.
- Validation result: status, format, size, resolusi, artifact risk.
- Error handling dan retry/fallback.
- Project history dan usage ledger.

### Agent Decision Pipeline

```mermaid
flowchart TD
  Input[User prompt/media/settings] --> Analyze[Analyze requirement]
  Analyze --> Intent[Detect intent and mode]
  Intent --> Safety[Safety and policy checks]
  Safety --> Prompt[Enhance prompt]
  Prompt --> Plan[Create workflow plan]
  Plan --> Params[Select parameters]
  Params --> Estimate[Estimate resource]
  Estimate --> Confirm[Ask user confirmation]
  Confirm --> Queue[Create job]
  Queue --> Execute[Execute provider workflow]
  Execute --> Validate[Validate result]
  Validate --> Store[Store output and metadata]
  Store --> Deliver[Deliver Telegram result]
  Validate -->|Recoverable failure| Retry[Retry or fallback]
  Retry --> Execute
```

### Prompt Intelligence Template

Hermes harus mengubah prompt sederhana menjadi format:

```text
Subject:
Style:
Camera Movement:
Environment:
Lighting:
Composition:
Motion:
Quality Settings:
Negative Prompt:
Provider Notes:
```

Contoh:

Input user:

```text
mobil sport di jalan kota malam
```

Enhanced prompt:

```text
Subject: A premium black sports car driving through a modern city at night, reflective bodywork, sharp aerodynamic profile.
Style: Cinematic automotive commercial, realistic, high contrast, premium brand mood.
Camera Movement: Low-angle tracking shot, smooth dolly movement, subtle speed ramp.
Environment: Wet asphalt city street, neon reflections, modern skyscrapers, light traffic.
Lighting: Dramatic neon rim lighting, soft streetlight highlights, controlled reflections.
Composition: Hero car centered in frame, dynamic leading lines, shallow depth of field.
Motion: Confident forward motion, realistic wheel blur, subtle atmospheric haze.
Quality Settings: Ultra detail, photorealistic, 4K-ready, clean texture, no distortion.
Negative Prompt: warped wheels, broken headlights, unreadable plates, low quality, artifacts.
Provider Notes: prioritize motion consistency and car body integrity.
```

### Model/Provider Selection Logic

Hermes memilih provider menggunakan scoring:

```text
score =
  capabilityMatch * 0.30 +
  qualityScore * 0.25 +
  quotaAvailability * 0.15 +
  costEfficiency * 0.10 +
  latencyScore * 0.10 +
  reliabilityScore * 0.10
```

Hard constraints:

- Provider harus mendukung capability yang diminta.
- Provider harus memiliki quota/credit cukup.
- Provider harus tidak sedang rate-limited.
- Output target harus sesuai batas provider.
- Safety/moderation harus lolos.

## 9. Database Design

### Core Tables

```mermaid
erDiagram
  users ||--o{ projects : owns
  users ||--o{ credit_ledger : has
  users ||--o{ usage_records : has
  projects ||--o{ generation_jobs : has
  projects ||--o{ media_assets : stores
  generation_jobs ||--o{ job_events : logs
  generation_jobs ||--o{ usage_records : consumes
  providers ||--o{ provider_accounts : has
  providers ||--o{ generation_jobs : executes

  users {
    uuid id PK
    bigint telegram_id UK
    string username
    string display_name
    string role
    string status
    string default_preset
    jsonb preferences
    timestamptz created_at
    timestamptz updated_at
  }

  projects {
    uuid id PK
    uuid user_id FK
    string title
    string type
    string status
    string preset
    bool is_favorite
    uuid duplicated_from_id
    jsonb settings
    jsonb prompt_snapshot
    timestamptz created_at
    timestamptz updated_at
  }

  generation_jobs {
    uuid id PK
    uuid project_id FK
    uuid user_id FK
    string mode
    string status
    string provider_id
    string provider_job_id
    int progress
    int retry_count
    jsonb request_payload
    jsonb enhanced_prompt
    jsonb resource_estimate
    jsonb resource_actual
    text error_code
    text error_message
    timestamptz queued_at
    timestamptz started_at
    timestamptz completed_at
  }

  media_assets {
    uuid id PK
    uuid project_id FK
    uuid job_id FK
    string kind
    string mime_type
    string storage_key
    string public_url
    int width
    int height
    int duration_ms
    int size_bytes
    jsonb metadata
    timestamptz created_at
  }

  credit_ledger {
    uuid id PK
    uuid user_id FK
    string type
    int credits_delta
    int tokens_delta
    int balance_after
    string reference_type
    uuid reference_id
    string note
    timestamptz created_at
  }

  usage_records {
    uuid id PK
    uuid user_id FK
    uuid job_id FK
    string provider_id
    int credits_used
    int tokens_used
    int storage_bytes_used
    jsonb usage_detail
    timestamptz created_at
  }

  providers {
    string id PK
    string display_name
    string status
    jsonb capabilities
    jsonb pricing_config
    jsonb limits_config
    timestamptz updated_at
  }

  provider_accounts {
    uuid id PK
    string provider_id FK
    string status
    string secret_ref
    int priority
    jsonb balance_snapshot
    jsonb rate_limit_snapshot
    timestamptz last_synced_at
  }

  job_events {
    uuid id PK
    uuid job_id FK
    string event_type
    jsonb payload
    timestamptz created_at
  }
```

### Additional Tables

- `user_sessions`: multi-step Telegram form state.
- `prompt_versions`: version history untuk prompt enhancement.
- `preset_configs`: preset prompt/system parameters.
- `webhook_events`: idempotency log untuk Telegram/provider webhook.
- `audit_logs`: admin action, credit adjustment, provider changes.
- `api_keys`: optional internal API keys untuk admin/tools.
- `storage_objects`: lifecycle metadata dan cleanup status.

### Data Integrity Rules

- Setiap credit change wajib masuk `credit_ledger`.
- Setiap job paid wajib punya `usage_records`.
- `generation_jobs.status` hanya boleh berpindah melalui state machine valid.
- Provider webhook harus idempotent berdasarkan provider event ID.
- Media asset tidak boleh dianggap tersedia sampai upload selesai dan checksum valid.

## 10. Queue Architecture

### Queue Names

| Queue | Fungsi |
|---|---|
| `image.generation` | Text-to-image dan image-to-image |
| `image.enhancement` | Upscale, remove bg, replace bg, enhancement |
| `video.generation` | Text-to-video dan image-to-video |
| `video.enhancement` | Upscale, interpolation, motion enhancement |
| `provider.sync` | Sync balance, rate limit, quota provider |
| `media.cleanup` | Cleanup temporary file dan lifecycle |
| `notification.delivery` | Telegram status/result delivery |

### Job State Machine

```text
draft -> estimated -> confirmed -> queued -> running -> validating -> storing -> completed
                                      |          |              |
                                      v          v              v
                                  cancelled  retrying        failed
```

### Retry Policy

- Provider timeout: retry maksimal 2 kali dengan exponential backoff.
- Rate limit: requeue dengan delay sesuai reset time.
- Insufficient provider credit: fallback provider jika tersedia.
- Invalid input: jangan retry, tampilkan error aman.
- Storage upload failure: retry upload maksimal 3 kali.
- Telegram delivery failure: simpan result tetap, retry notification.

### Priority

- `priority 1`: paid ultra/high quality job.
- `priority 2`: standard paid job.
- `priority 3`: enhancement ringan.
- `priority 4`: provider sync/cleanup.

### Queue Monitoring

Dashboard harus menampilkan:

- Waiting, active, completed, failed.
- Average queue wait time.
- Provider failure rate.
- Retry count.
- Stuck jobs.
- Queue position untuk user.

## 11. Storage Architecture

### Storage Layout

```text
s3://ai-creator-studio-telegram/
  users/
    {userId}/
      projects/
        {projectId}/
          inputs/
            {assetId}.{ext}
          outputs/
            {jobId}/
              result.{ext}
              thumbnail.{ext}
              metadata.json
          exports/
            prompt-{version}.txt
  temp/
    {jobId}/
  system/
    presets/
    provider-samples/
```

### Storage Rules

- Input/output media disimpan di object storage, bukan database.
- Database hanya menyimpan metadata, storage key, URL, checksum, size.
- Public URL harus signed/temporary untuk private project.
- Thumbnail dibuat untuk preview Telegram dan dashboard.
- Temporary objects punya TTL cleanup.
- Storage usage dihitung per user dan direkam di usage dashboard.

### Media Validation

- Validasi MIME type dan size.
- Validasi image dimension/video duration.
- Scan extension mismatch.
- Limit upload per user berdasarkan plan/credit.
- Jangan percaya metadata dari client; lakukan server-side validation.

## 12. API Design

API internal dipakai oleh bot, worker, admin dashboard, dan Hermes integration layer.

### Auth

- Bot ke API: internal service token via env.
- Admin dashboard: session auth/JWT dengan role admin.
- Provider webhook: signature verification.
- Hermes integration: scoped internal token atau local IPC jika di server yang sama.

### REST Endpoints

| Method | Endpoint | Fungsi |
|---|---|---|
| `GET` | `/health` | Healthcheck service |
| `GET` | `/metrics` | Metrics untuk monitoring |
| `POST` | `/telegram/webhook` | Telegram webhook receiver |
| `GET` | `/users/:id/usage` | Usage dashboard user |
| `GET` | `/users/:id/projects` | Project library user |
| `POST` | `/projects` | Membuat project draft |
| `GET` | `/projects/:id` | Detail project |
| `PATCH` | `/projects/:id` | Update title/favorite/settings |
| `POST` | `/projects/:id/duplicate` | Duplicate project |
| `POST` | `/projects/:id/export-prompt` | Export prompt |
| `POST` | `/generation/estimate` | Estimasi resource |
| `POST` | `/generation/confirm` | Confirm dan enqueue job |
| `GET` | `/jobs/:id` | Status job |
| `POST` | `/jobs/:id/cancel` | Cancel job |
| `POST` | `/jobs/:id/regenerate` | Regenerate dari prompt/settings |
| `GET` | `/providers/status` | Provider status dan quota snapshot |
| `POST` | `/providers/sync` | Trigger provider sync |

### Example Request: Estimate

```json
{
  "userId": "uuid",
  "mode": "text_to_video",
  "prompt": "mobil sport di jalan kota malam",
  "preset": "cinematic",
  "settings": {
    "aspectRatio": "9:16",
    "duration": "8s",
    "resolution": "1080p",
    "fps": 24,
    "quality": "high"
  }
}
```

### Example Response: Estimate

```json
{
  "estimateId": "uuid",
  "enhancedPrompt": {
    "subject": "...",
    "style": "...",
    "cameraMovement": "...",
    "environment": "...",
    "lighting": "...",
    "composition": "...",
    "motion": "...",
    "qualitySettings": "..."
  },
  "workflowPlan": {
    "mode": "text_to_video",
    "providerPreference": ["auto"],
    "steps": ["prompt_enhancement", "video_generation", "validation", "storage"]
  },
  "resourceEstimate": {
    "credits": 120,
    "tokens": 2400,
    "storageBytes": 36700160,
    "etaSecondsMin": 120,
    "etaSecondsMax": 360
  },
  "confirmationRequired": true
}
```

### Error Response Pattern

```json
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Credits are not enough for this generation.",
    "safeDetail": "Please reduce quality settings or top up your credits."
  }
}
```

## 13. Folder Structure

Recommended monorepo structure:

```text
/root/hermes-projects/AI Creator Studio Telegram/
  README.md
  .env.example
  package.json
  pnpm-workspace.yaml
  turbo.json
  docker-compose.yml
  ecosystem/
    systemd/
      ai-creator-studio-telegram-api.service
      ai-creator-studio-telegram-bot.service
      ai-creator-studio-telegram-worker.service
    caddy/
      Caddyfile.example
  apps/
    bot/
      src/
        index.ts
        config/
        commands/
        keyboards/
        scenes/
        handlers/
        presenters/
        middlewares/
        services/
        types/
    api/
      src/
        server.ts
        config/
        routes/
        controllers/
        services/
        repositories/
        middlewares/
        schemas/
        types/
    worker/
      src/
        index.ts
        queues/
        processors/
        providers/
        validators/
        services/
        types/
    admin-web/
      app/
      components/
      constants/
      hooks/
      lib/
      services/
      types/
  packages/
    database/
      prisma/
        schema.prisma
        migrations/
      src/
    core/
      src/
        constants/
        errors/
        logger/
        result/
        types/
    prompts/
      src/
        presets/
        prompt-builder.ts
        prompt-enhancer.ts
    provider-adapters/
      src/
        base/
        mock/
        image/
        video/
    storage/
      src/
        s3-client.ts
        storage-service.ts
    queue/
      src/
        bullmq.ts
        queue-names.ts
    telegram-ui/
      src/
        cards/
        menus/
        formatters/
  docs/
    PRD.md
    ARCHITECTURE.md
    API.md
    SECURITY.md
    DEPLOYMENT.md
    ROADMAP.md
  scripts/
    check-env.ts
    sync-provider-balances.ts
    cleanup-temp-media.ts
  tests/
    unit/
    integration/
```

### Separation of Concerns

- Bot hanya mengelola Telegram UX, bukan provider logic.
- API mengelola contracts, auth, persistence, dan orchestration boundary.
- Worker mengelola eksekusi job berat.
- Provider adapter hanya bicara dengan provider.
- Prompt package mengelola preset dan prompt intelligence.
- Core package menampung shared types, error, logger, constants.

## 14. Security Design

### Secret Management

- Semua token/API key disimpan di `.env`, bukan di code.
- `.env.example` hanya berisi nama variable dan placeholder.
- Provider credential disimpan sebagai env atau secret reference.
- Jangan kirim secret ke Telegram/admin UI/log.

### Required Environment Variables

```text
NODE_ENV=
APP_BASE_URL=
TELEGRAM_BOT_TOKEN=
TELEGRAM_WEBHOOK_SECRET=
INTERNAL_API_TOKEN=
DATABASE_URL=
REDIS_URL=
S3_ENDPOINT=
S3_REGION=
S3_BUCKET=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
S3_PUBLIC_BASE_URL=
HERMES_AGENT_ENDPOINT=
HERMES_AGENT_TOKEN=
ADMIN_EMAIL=
ADMIN_PASSWORD_HASH=
PROVIDER_DEFAULT_TIMEOUT_MS=
```

Provider env placeholder:

```text
OPENAI_API_KEY=
RUNWAY_API_KEY=
KLING_API_KEY=
PIKA_API_KEY=
HAILUO_API_KEY=
VEO_API_KEY=
SEEDANCE_API_KEY=
```

Aktifkan hanya provider yang tersedia. Jangan hardcode asumsi provider tertentu.

### Input Validation

- Validasi command dan callback data Telegram.
- Validasi prompt length, media type, media size.
- Validasi aspect ratio, resolution, duration, fps, quality terhadap allowlist.
- Validasi user balance sebelum enqueue.
- Validasi provider response sebelum storage dan delivery.

### Authorization

- User hanya boleh membaca project miliknya.
- Admin dashboard wajib role-based access.
- Internal API token harus scoped.
- Provider webhook wajib signature verification dan idempotency key.

### Abuse Protection

- Rate limit per user, per command, dan per generation.
- Prompt/content safety check sebelum provider call.
- Daily/monthly usage cap per user.
- Blocklist dan manual suspension status.
- Audit log untuk admin changes.

### Error Handling

- Error user-facing harus aman dan informatif.
- Error internal masuk structured log dengan correlation ID.
- Jangan membocorkan stack trace atau provider secret.
- Job failure tetap menyimpan event history.

## 15. Scalability Design

### Horizontal Scaling

- Bot/API stateless; session state disimpan di Redis/PostgreSQL.
- Worker bisa diskalakan per queue: image worker dan video worker terpisah.
- Provider router menghindari provider yang quota habis/rate-limited.
- Storage pakai S3-compatible agar tidak membebani VPS disk.

### Performance Strategy

- Async queue untuk semua generation.
- Cache provider balance/rate limit dengan TTL.
- Thumbnail generation asynchronous.
- Pagination untuk project library.
- Batasi ukuran payload di Telegram/API.
- Gunakan signed URL untuk media besar.

### Reliability Strategy

- Idempotency key untuk Telegram callback dan provider webhook.
- Retry/fallback policy berbasis error type.
- Dead-letter queue untuk job gagal.
- Healthcheck per service.
- Graceful shutdown worker agar job tidak corrupt.
- Periodic provider balance sync.

### Observability

Minimal metrics:

- `jobs_queued_total`
- `jobs_completed_total`
- `jobs_failed_total`
- `job_duration_seconds`
- `provider_request_total`
- `provider_failure_rate`
- `credits_consumed_total`
- `tokens_consumed_total`
- `storage_bytes_total`
- `telegram_delivery_failure_total`

Log fields:

```text
timestamp, service, requestId, userId, projectId, jobId, providerId, event, status, durationMs, errorCode
```

## 16. Deployment Architecture

### VPS Target

```text
Host: root@187.77.119.32
Project path: /root/hermes-projects/AI Creator Studio Telegram
Service slug: ai-creator-studio-telegram
```

### Deployment Options

#### Option A: Docker Compose

Recommended untuk production karena service boundary lebih jelas.

Services:

- `postgres`
- `redis`
- `api`
- `bot`
- `worker-image`
- `worker-video`
- `admin-web`
- optional `minio` jika belum memakai object storage external.

#### Option B: systemd + local services

Recommended jika ingin mengikuti project Hermes VPS existing yang sederhana.

Services:

- `ai-creator-studio-telegram-api.service`
- `ai-creator-studio-telegram-bot.service`
- `ai-creator-studio-telegram-worker.service`
- PostgreSQL/Redis memakai service OS atau Docker.

### Caddy/Reverse Proxy

Admin/dashboard dan Telegram webhook butuh HTTPS. Contoh domain:

```text
creator-studio.example.com -> admin-web/api
creator-studio.example.com/telegram/webhook -> api
```

### Deployment Steps

```bash
ssh root@187.77.119.32
mkdir -p "/root/hermes-projects/AI Creator Studio Telegram"
cd "/root/hermes-projects/AI Creator Studio Telegram"
```

Setelah project dibuat:

```bash
cp .env.example .env
nano .env
pnpm install
pnpm db:migrate
pnpm build
pnpm start
```

Jika memakai systemd:

```bash
systemctl daemon-reload
systemctl enable ai-creator-studio-telegram-api.service
systemctl enable ai-creator-studio-telegram-bot.service
systemctl enable ai-creator-studio-telegram-worker.service
systemctl start ai-creator-studio-telegram-api.service
systemctl start ai-creator-studio-telegram-bot.service
systemctl start ai-creator-studio-telegram-worker.service
systemctl status ai-creator-studio-telegram-bot.service --no-pager
```

### Verification

```bash
find /root/hermes-projects -maxdepth 1 -mindepth 1 -type d | sort
ls -la "/root/hermes-projects/AI Creator Studio Telegram"
journalctl -u ai-creator-studio-telegram-bot.service -n 100 --no-pager
journalctl -u ai-creator-studio-telegram-worker.service -n 100 --no-pager
```

## 17. Development Roadmap

### Phase 0: Foundation

- Finalize product requirements, architecture, and provider adapter contracts.
- Create monorepo TypeScript structure.
- Add `.env.example`, README, lint, typecheck, formatting.
- Setup PostgreSQL, Redis, Prisma, queue, logger.
- Create mock provider for end-to-end dry run.

Exit criteria:

- Bot can run `/start`, `/token`, `/usage`, `/projects`.
- Mock generation completes through queue and saves result metadata.
- Lint/typecheck/build pass.

### Phase 1: Telegram MVP

- Implement premium Telegram UI with inline keyboard and multi-step form.
- Implement Image Studio text-to-image and image-to-image.
- Implement Video Studio text-to-video and image-to-video with mock/real provider placeholder.
- Implement prompt enhancement, preset configs, resource estimate, confirmation screen.
- Implement project library, favorite, duplicate, regenerate, export prompt.

Exit criteria:

- User can complete generation flow from Telegram.
- Job progress and result card work.
- Usage ledger updates correctly.

### Phase 2: Provider Integration

- Integrate real provider adapters based on available API keys.
- Add provider balance/token/quota sync.
- Add provider router scoring.
- Add retry/fallback for provider failures.
- Add media validation and S3 storage.

Exit criteria:

- Real provider job completes and is stored.
- Insufficient quota and rate limit are handled safely.

### Phase 3: Advanced Media Features

- Background removal/replacement.
- Style transfer and image enhancement.
- Video upscale, frame interpolation, motion enhancement.
- Thumbnail generation and preview optimization.

Exit criteria:

- Enhancement workflows have estimates, queue, storage, result card.
- Media quality validation is implemented.

### Phase 4: Admin Dashboard

- Next.js dashboard for users, projects, jobs, providers, quota, storage.
- Admin credit adjustment with audit log.
- Queue monitor and failed job retry UI.
- Provider health and error analytics.

Exit criteria:

- Admin can monitor usage, active jobs, failed jobs, provider quota.
- Admin actions are audited.

### Phase 5: Production Hardening

- Add automated tests for prompt builder, provider router, credit ledger, job state machine.
- Add backup strategy for PostgreSQL.
- Add alerting for queue stuck, provider failure spike, low provider balance.
- Add storage lifecycle cleanup.
- Add security review and deployment runbook.

Exit criteria:

- Production runbook complete.
- Critical flows tested.
- Observability and alerting active.

## Preset System

### Presets

| Preset | Primary Use | Prompt Bias |
|---|---|---|
| Cinematic | Film-like output | camera, lighting, mood, composition |
| Product Ads | Product hero | product clarity, reflective surface, clean set |
| Commercial Ads | Campaign visuals | polished, brand-ready, persuasive |
| UGC | Social creator | handheld, natural, relatable |
| Luxury Brand | Premium brand | minimal, elegant, high-end materials |
| Automotive | Cars/mobility | motion, reflections, road environment |
| Technology | Devices/SaaS/AI | clean, futuristic, precise |
| Fashion | Model/apparel | styling, fabric, editorial framing |
| Documentary | Real-world narrative | natural light, authentic environment |
| Realistic | Photorealism | texture accuracy, natural lighting |
| Anime | Stylized animation | character design, color, linework |
| Drone Shot | Aerial scene | altitude, sweeping movement, geography |
| Action Scene | Dynamic scene | speed, impact, motion clarity |
| Social Media Reel | Vertical content | 9:16, strong hook, fast visual clarity |

### Image Settings

Aspect ratio allowlist:

```text
1:1, 4:5, 9:16, 16:9, 21:9
```

Resolution allowlist:

```text
HD, Full HD, 2K, 4K
```

Quality allowlist:

```text
Standard, High, Ultra
```

### Video Settings

Duration allowlist:

```text
5s, 8s, 10s, 15s, 30s, 60s
```

Resolution allowlist:

```text
720p, 1080p, 2K, 4K
```

FPS allowlist:

```text
24, 30, 60
```

Quality allowlist:

```text
Standard, High, Ultra
```

## Credits & Token Management

### Dashboard Fields

User dashboard harus menampilkan:

- Available Credits
- Available Tokens
- Usage Today
- Usage This Month
- Remaining Balance
- Active Jobs
- Queue Status
- Storage Usage

Provider dashboard harus menampilkan:

- Provider credit balance.
- Provider token balance.
- Rate limit.
- Daily quota.
- Monthly quota.
- Last sync time.
- Provider health status.

### Estimation Rules

Sebelum generation:

- Hitung base cost dari mode.
- Tambahkan multiplier resolution, duration, fps, quality.
- Tambahkan provider-specific cost jika diketahui.
- Tambahkan estimasi token prompt/agent.
- Tambahkan estimasi storage.
- Tampilkan ETA range.

Setelah generation:

- Rekam actual credits/tokens.
- Rekam storage bytes.
- Rekam provider cost/metadata jika tersedia.
- Tampilkan actual usage di result card.

## Quality Assurance Checklist

### Automated Checks

- `pnpm lint`
- `pnpm typecheck`
- `pnpm test`
- `pnpm build`
- Prisma migration validation.
- Queue worker dry run dengan mock provider.

### Manual Testing

- `/start` menampilkan main menu.
- `/token` menampilkan credit/token/active jobs.
- `/usage` menampilkan usage today/month/storage.
- `/projects` menampilkan empty state dan project list.
- Text-to-image flow sampai preview estimate.
- Confirm generation membuat job.
- Progress card berubah sesuai state.
- Result card punya download/regenerate/favorite/export prompt.
- Insufficient credit menampilkan error aman.
- Provider failure masuk retry/fallback atau failed state.
- Project hanya bisa diakses owner.

## Implementation Principles

- Jangan overengineering state management; mulai dengan session state sederhana di Redis dan DB.
- Jangan letakkan business logic di Telegram handler.
- Jangan menggabungkan provider API call dengan prompt builder.
- Jangan menyimpan file besar di repository atau database.
- Jangan menampilkan secret, stack trace, atau provider raw error ke user.
- Gunakan TypeScript strict mode.
- Gunakan constants/config untuk preset, mode, duration, resolution, fps, quality.
- Buat adapter provider yang mudah diganti.
- Mulai dengan mock provider agar end-to-end workflow bisa diuji tanpa biaya.