# Spesifikasi Keperluan Perisian (SRS)

## Bifrost — Jambatan AI antara Pengguna & Pembangun

| | |
|---|---|
| **Nama Projek** | Bifrost |
| **Versi Dokumen** | 1.0 |
| **Tarikh** | 11 September 2026 |
| **Penyedia** | Pasukan Kejuruteraan Bifrost |
| **Status** | Draf untuk Pembangunan (MVP) |

---

## 1. Pengenalan

### 1.1 Tujuan
Dokumen ini menerangkan keperluan perisian untuk **Bifrost**, satu platform SaaS yang bertindak sebagai jambatan automatik antara pengguna (bukan teknikal) dan pembangun perisian. Bifrost menerima input pengguna dalam pelbagai bentuk, memproses melalui saluran paip multi-agent AI, dan menghasilkan output yang sedia untuk pembangunan — ticket, PRD, draf kod, kes ujian, dan changelog dalam bahasa manusia.

### 1.2 Skop
Sistem ini adalah aplikasi web (SaaS) yang:
- Menerima permintaan pengguna melalui form web, screenshot, nota suara, dan mesej WhatsApp
- Menjalankan sesi klarifikasi interaktif dengan AI
- Menyelidik rujukan (GitHub, YouTube, Web, RSS) secara automatik
- Menjana ticket pembangunan berstruktur + PRD + draf kod + kes ujian
- Menyediakan dashboard developer untuk semakan & pengesahan

### 1.3 Definisi & Singkatan

| Singkatan | Maksud |
|---|---|
| PRD | Product Requirements Document |
| SRS | Software Requirements Specification |
| MVP | Minimum Viable Product |
| ACP | Agent Client Protocol (Reasonix) |
| LLM | Large Language Model |
| AC | Acceptance Criteria |
| REST | Representational State Transfer |

---

## 2. Penerangan Sistem

### 2.1 Seni Bina Sistem

```
┌─────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Pengguna  │───▶│  Frontend Web    │───▶│  API (FastAPI)  │
│ (Web/WA/TG) │    │  (Next.js/SPA)   │    │  Python         │
└─────────────┘    └──────────────────┘    └────────┬────────┘
                                                    │
                          ┌─────────────────────────┤
                          ▼                         ▼
               ┌──────────────────┐      ┌──────────────────┐
               │  AI Orchestrator │      │  Agent-Reach     │
               │  (Reasonix ACP)  │─────▶│  (GitHub, YouTube│
               │  Multi-agent     │      │   Web, RSS)      │
               └────────┬─────────┘      └──────────────────┘
                        ▼
              ┌─────────────────────────┐
              │  LLM: deepseek-v4-flash │
              │  via api.mireld.my      │
              └────────────┬────────────┘
                           ▼
              ┌─────────────────────────┐
              │  PostgreSQL + pgvector  │
              │  (tickets, users,       │
              │   embeddings)           │
              └─────────────────────────┘
```

### 2.2 Peranan Pengguna

| Peranan | Penerangan | Kebenaran |
|---|---|---|
| **End-User** | Pengguna bukan teknikal yang hantar permintaan | Hantar request, jawab soalan klarifikasi, lihat status ticket |
| **Developer** | Ahli pasukan teknikal | Lihat semua ticket, semak PRD, terima/edit ticket, generate code |
| **Admin** | Pemilik workspace | Urus ahli, set plan, konfigurasi integrasi, lihat semua data |

---

## 3. Keperluan Fungsional (Functional Requirements)

### FR-001: Input Antaramuka

**Penerangan:** Pengguna boleh menghantar permintaan melalui teks, screenshot, nota suara, atau lampiran fail.

| ID | Keperluan | Utama |
|---|---|---|
| FR-001.1 | Sistem menerima input teks melalui form web (min 10 aksara, maks 5000 aksara) | Ya |
| FR-001.2 | Sistem menerima muat naik gambar (screenshot) sehingga 10MB (PNG/JPG) | Ya |
| FR-001.3 | Sistem menerima rakaman suara sehingga 5 minit (transkripsi automatik) | Tidak (fasa 2) |
| FR-001.4 | Sistem menerima input melalui mesej WhatsApp/Telegram (integrasi bot) | Tidak (fasa 2) |
| FR-001.5 | Sistem menyokong Bahasa Melayu & Bahasa Inggeris | Ya |

**Kriteria Penerimaan:** Pengguna boleh hantar teks + screenshot serentak, dan sistem menyimpan input dalam masa <2 saat.

---

### FR-002: AI Clarification (Klarifikasi Pintar)

**Penerangan:** Sistem bertanya soalan susulan untuk mengurangkan kekaburan permintaan sebelum menjana ticket.

| ID | Keperluan | Utama |
|---|---|---|
| FR-002.1 | Sistem menjana 2-5 soalan klarifikasi berdasarkan input pengguna | Ya |
| FR-002.2 | Soalan dipaparkan sebagai pilihan jawapan (quick replies) + medan teks bebas | Ya |
| FR-002.3 | Pengguna boleh memilih untuk skip (biar AI buat andaian munasabah) | Ya |
| FR-002.4 | Sistem merekod semua jawapan untuk konteks generasi ticket | Ya |
| FR-002.5 | Jika maklumat tidak mencukupi selepas 5 soalan, sistem generate ticket dengan andaian yang dinyatakan | Ya |

**Kriteria Penerimaan:** 90% permintaan dapat diklasifikasikan (bug/feature/enhancement) selepas maksimum 2 pusingan klarifikasi.

---

### FR-003: Agent-Reach Research

**Penerangan:** Sistem menjalankan penyelidikan automatik menggunakan agent-reach untuk mencari rujukan industri.

| ID | Keperluan | Utama |
|---|---|---|
| FR-003.1 | Sistem mencari isu/penyelesaian serupa di GitHub (repo awam) | Ya |
| FR-003.2 | Sistem mencari tutorial video di YouTube berkaitan topik | Tidak (fasa 2) |
| FR-003.3 | Sistem mencari artikel & dokumentasi web | Ya |
| FR-003.4 | Hasil research disimpan sebagai lampiran dalam ticket (link + ringkasan) | Ya |
| FR-003.5 | Research dijalankan dalam masa <60 saat | Ya |

**Kriteria Penerimaan:** Setiap ticket MVP mengandungi min 2 rujukan luar yang relevan.

---

### FR-004: Ticket Generation

**Penerangan:** Sistem menjana ticket pembangunan berstruktur daripada input + klarifikasi + research.

| ID | Keperluan | Utama |
|---|---|---|
| FR-004.1 | Ticket mengandungi: tajuk, ringkasan, jenis (bug/feature/enhancement), prioriti | Ya |
| FR-004.2 | Ticket mengandungi Acceptance Criteria (3-5 item yang boleh diuji) | Ya |
| FR-004.3 | Ticket mengandungi PRD ringkas (objektif, latar belakang, keperluan, risiko) | Ya |
| FR-004.4 | Prioriti auto-ditentukan oleh AI: High/Medium/Low | Ya |
| FR-004.5 | Setiap ticket mempunyai ID unik (cth: BIF-1042) | Ya |
| FR-004.6 | Draf kod dijana untuk feature/bug yang mudah (opsional) | Tidak (fasa 2) |

**Kriteria Penerimaan:** Ticket dijana dalam <10 minit selepas input, dengan ketepatan >85% (dinilai oleh dev).

---

### FR-005: Dev Dashboard

**Penerangan:** Antaramuka untuk developer melihat dan mengurus ticket.

| ID | Keperluan | Utama |
|---|---|---|
| FR-005.1 | Senarai ticket dengan filter (status, prioriti, tag, tarikh) | Ya |
| FR-005.2 | Lihat detail ticket (PRD, AC, code, history, rujukan) | Ya |
| FR-005.3 | Developer boleh terima/edit/tolak ticket | Ya |
| FR-005.4 | Statistik ringkas: jumlah ticket, purata masa proses, status | Ya |
| FR-005.5 | Pencarian ticket oleh ID/tajuk | Ya |

---

### FR-006: Changelog Generation

**Penerangan:** Sistem menghasilkan changelog dalam bahasa manusia untuk pengguna.

| ID | Keperluan | Utama |
|---|---|---|
| FR-006.1 | Changelog auto-dijana apabila ticket ditandakan "Siap" | Ya |
| FR-006.2 | Ditulis dalam bahasa mudah (takde jargon teknikal) | Ya |
| FR-006.3 | Boleh dihantar kepada pengguna melalui email/Telegram | Tidak (fasa 2) |

---

### FR-007: User Notification

**Penerangan:** Sistem memberitahu pengguna status permintaan mereka.

| ID | Keperluan | Utama |
|---|---|---|
| FR-007.1 | Pengguna boleh lihat status ticket melalui link shareable | Ya |
| FR-007.2 | Notifikasi email apabila ticket siap (opsional) | Tidak (fasa 2) |
| FR-007.3 | Notifikasi Telegram/WhatsApp (jika integrasi aktif) | Tidak (fasa 2) |

---

## 4. Keperluan Bukan Fungsional (Non-Functional Requirements)

### NFR-001: Prestasi

| Metrik | Sasaran |
|---|---|
| Masa proses AI (input → ticket) | <10 minit |
| Masa research agent-reach | <60 saat |
| Latency API (purata) | <500ms |
| Masa muat halaman dashboard | <2 saat |

### NFR-002: Keselamatan

- API key dienkripsi (env vars, tidak dalam repo)
- Tiada kod pengguna dieksekusi di server — hanya draft text
- HTTPS wajib (TLS 1.2+)
- Pengesahan pengguna: JWT token, 24h expiry
- Rate limiting: 60 request/minit setiap IP

### NFR-003: Kebolehpercayaan

- Ketersediaan >99.5% (bulanan)
- Backup database harian (R2)
- Recovery point objective (RPO): <24 jam

### NFR-004: Kebolehskalaan

- Menyokong 100 pengguna serentak (fasa 1)
- Seni bina stateless untuk worker AI (boleh scale horizontal)
- Penggunaan token LLM dioptimumkan melalui Reasonix ACP (subagent)

### NFR-005: Kebolehgunaan

- Mobile-first responsive (pengguna banyak guna telefon)
- Sokongan Bahasa Melayu & Inggeris
- Onboarding <5 minit

---

## 5. Keperluan Antaramuka (UI/UX)

### 5.1 Mockup / Halaman Utama

| Halaman | Penerangan |
|---|---|
| **Landing Page** | Penerangan produk, flow, CTA "Cuba Percuma" |
| **User Input** | Form hantar permintaan (teks/screenshot/voice/file + contoh cepat) |
| **Clarify Chat** | Chat interaktif AI tanya soalan susulan (quick reply) |
| **Dev Dashboard** | Statistik + senarai ticket + filter |
| **Ticket Detail** | PRD + AC + draf kod + timeline + rujukan research |

### 5.2 API Endpoints

| Method | Endpoint | Penerangan |
|---|---|---|
| POST | `/api/requests` | Hantar permintaan baru |
| GET | `/api/requests/{id}/clarify` | Soalan klarifikasi |
| POST | `/api/requests/{id}/answers` | Hantar jawapan klarifikasi |
| POST | `/api/requests/{id}/process` | Mula proses AI |
| GET | `/api/tickets/{id}` | Detail ticket |
| GET | `/api/tickets` | Senarai ticket (filter/pagination) |
| PATCH | `/api/tickets/{id}` | Update status ticket |
| GET | `/api/dashboard/stats` | Statistik dashboard |
| POST | `/api/auth/login` | Login |
| GET | `/api/changelog/{ticketId}` | Changelog untuk ticket |

---

## 6. Keperluan Data

### 6.1 Skema PostgreSQL (Ringkas)

```sql
-- Pengguna
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    name VARCHAR(120) NOT NULL,
    role VARCHAR(20) DEFAULT 'end_user',
    workspace_id UUID REFERENCES workspaces(id),
    created_at TIMESTAMPTZ DEFAULT now()
);

-- Request (input asal dari user)
CREATE TABLE requests (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    input_type VARCHAR(20),          -- text/screenshot/voice/file
    content TEXT NOT NULL,
    attachments JSONB,
    clarification JSONB,             -- soalan + jawapan
    status VARCHAR(20) DEFAULT 'pending',  -- pending/clarifying/processing/done
    created_at TIMESTAMPTZ DEFAULT now()
);

-- Ticket (output AI)
CREATE TABLE tickets (
    id SERIAL PRIMARY KEY,           -- BIF-1042 -> id=1042
    request_id UUID REFERENCES requests(id),
    title VARCHAR(255) NOT NULL,
    summary TEXT NOT NULL,
    ticket_type VARCHAR(20),         -- bug/feature/enhancement
    priority VARCHAR(10),            -- high/medium/low
    status VARCHAR(20) DEFAULT 'open', -- open/in_dev/done/rejected
    prd JSONB,
    acceptance_criteria JSONB,
    draft_code TEXT,
    research_refs JSONB,
    created_by VARCHAR(20) DEFAULT 'bifrost_ai',
    created_at TIMESTAMPTZ DEFAULT now()
);

-- Embeddings (untuk carian semantik ticket lama)
CREATE TABLE embeddings (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    ticket_id INT REFERENCES tickets(id),
    content_type VARCHAR(20),        -- summary/prd/ac
    embedding VECTOR(768),
    created_at TIMESTAMPTZ DEFAULT now()
);
```

### 6.2 Penyimpanan Fail

- Screenshot/audio disimpan di **Cloudflare R2** (bucket `bifrost-uploads`)
- URL presigned untuk muat naik/baca
- Tempoh simpanan: 90 hari

---

## 7. Kekangan Reka Bentuk

1. **Multi-agent wajib guna Reasonix ACP** — semua tugas coding/penyelidikan delegation melalui `reasonix acp --model deepseek-flash` untuk jimat token sesi utama
2. **LLM utama: api.mireld.my** (`deepseek-v4-flash`) — semua panggilan LLM production guna provider ini
3. **Keutamaan efisiensi token** — context disimpan kecil; subagent isolation untuk tugas berat
4. **Tiada eksekusi kod pengguna di server** — draf kod adalah teks sahaja, dev yang run
5. **Deployment: Cloudflare Pages** (frontend) + **VPS/API** (backend FastAPI)
6. **Penyelidikan guna agent-reach** — GitHub API, Jina Reader, RSS; Reddit/Twitter perlukan cookies (opsional)

---

## 8. Matriks Keterkesanan (Traceability)

| Keperluan | Asal (BRS) | Status |
|---|---|---|
| FR-001 Input | BRS §4 (Skop) | Fasa 1 |
| FR-002 Clarification | BRS §4 (Skop) | Fasa 1 |
| FR-003 Research | BRS §4 (Skop) | Fasa 1 |
| FR-004 Ticket Gen | BRS §4 (Skop) | Fasa 1 |
| FR-005 Dev Dashboard | BRS §3 (Objektif) | Fasa 1 |
| FR-006 Changelog | BRS §4 (Skop) | Fasa 1-2 |
| FR-007 Notification | BRS §4 (Skop) | Fasa 2 |

---

## 9. Lampiran

- **Lampiran A:** Mockup HTML — `/root/bifrost/mockups/` (5 halaman)
- **Lampiran B:** BRS — `/root/bifrost/BRS.md`
- **Lampiran C:** Stack rujukan: FastAPI docs, Reasonix ACP, agent-reach skill

---

*Dokumen ini adalah draf awal untuk pembangunan MVP Bifrost. Ia akan dikemas kini selepas semakan pasukan.*