Struktur Folder & Cara Kerja

Struktur Folder & Cara Kerja

Struktur penting (setelah ekstrak ZIP)

kartaya/
├── package.json          # scripts: setup, dev, worker, build, pack:buyer, …
├── pnpm-lock.yaml
├── docker-compose.yml    # Postgres :5434 + Redis :6380 saja
├── .env.example          # template nama variabel (salin ke .env.local)
├── prisma/
│   ├── schema.prisma
│   └── seed.ts           # kategori & SkillTemplate awal
├── scripts/
│   ├── worker.ts         # proses BullMQ
│   └── pack-buyer.sh     # ZIP bersih untuk distribusi
├── src/
│   ├── routes/           # halaman UI (/, /generator, /jobs, …)
│   ├── server/
│   │   ├── fn/           # server functions
│   │   ├── services/     # generate-cards, pack-product, ai/, storage/
│   │   └── lib/          # crypto, text/template, …
│   └── generated/prisma/ # client Prisma (di-generate)
├── docs/                 # PANDUAN-SETUP, SPESIFIKASI, ASET-HAK
├── storage/              # runtime lokal (tidak ikut ZIP/git)
└── LICENSE

Folder yang sengaja tidak ada di ZIP pembeli (lihat scripts/pack-buyer.sh): .git, node_modules, .env / .env.local, output/, storage/, artefak dist / .output / .nitro, dll.

Model data inti (Prisma)

Antara lain: SkillTemplate, Category, GenerationJob, Flashcard, ProductPack, AiCredential, AiUsage, ModelPrice, AppSettings.

Status job: QUEUED | RUNNING | DONE | FAILED.
Mode storage: LOCAL | S3 | GDRIVE.
Jenis AI credential: TEXT | IMAGE.

Cara kerja (alur job)

1. Aksi UI memanggil server function.
2. Baris GenerationJob / ProductPack ditulis ke Postgres; job di-enqueue ke BullMQ (Redis).
3. Proses terpisah pnpm worker menjalankan generate-cards atau pack-product.
4. Progress ditulis kembali ke baris job; UI mem-poll status.
5. Generate kartu: LLM → JSON kosakata (anti-duplikat slug) → render promptTemplate → provider image → storage + thumbnail → Flashcard.
6. Pemanggilan AI lewat helper ter-track (selalu mencatat AiUsage + estimasi biaya).

Diagram alur (Mermaid)

Salin ke mermaid.live jika diagram tidak ter-render otomatis di pembaca Anda.

flowchart LR
  UI[UI TanStack Start] -->|server fn| SF[Server functions]
  SF -->|insert + enqueue| DB[(PostgreSQL)]
  SF --> Q[(Redis / BullMQ)]
  W[pnpm worker] --> Q
  W -->|generate-cards / pack-product| AI[AI TEXT + IMAGE]
  W --> ST[Storage LOCAL / S3 / Drive]
  W -->|progress / hasil| DB
  UI -->|poll getJob| DB
  AI --> Usage[AiUsage + ModelPrice]

Catatan arsitektur

• Single-user, tanpa auth.
• Antrian: concurrency job 1; fan-out generate gambar di dalam job dibatasi (pool lokal).
• File lokal dilayani /api/files?path=… (di dev ada plugin Vite khusus agar permintaan gambar tidak tertelan Nitro).