Decisions
- Tech stack (web framework, mobile approach) · Phase 1 · ready
- Hosting strategy (local-first vs cloud) · Phase 1 · ready
- Auth model (single-user vs multi-user) · Phase 1 · ready
User Tasks
- Define must-have features for v1 · Phase 1 · ready
- Review wireframes / mockups · Phase 2 · blocked
Summary
Build a custom UI for phone, tablet, and laptop that replaces Obsidian as the primary interface to the vault. Backend remains Markdown files and databases.
Problem / Motivation
Obsidian is great for Markdown editing but has limitations as the Opus system grows:
- No custom workflows (feature lifecycle, dashboards, inbox processing)
- Mobile app is limited and slow for structured interactions
- Can’t integrate deeply with Claude/LLM interactions
- No real-time sync or collaboration features tailored to Opus
- UI can’t be customized for specific Opus concepts (features, briefings, tasks)
A custom UI enables purpose-built views, better mobile experience, and tighter integration with the AI backend.
Proposed Solution
Build a web app (responsive for all devices) with:
- Backend: API layer that reads/writes the existing Markdown vault + optional database for metadata/search
- Frontend: Responsive web UI with views tailored to Opus workflows
- Storage: Markdown files remain the source of truth. Database layer for indexing, search, and fast queries
- Sync: File watcher keeps DB in sync with Markdown changes (from any source)
Open Questions
1. Tech Stack
Question: Which framework/stack to use?
| Option | Description |
|---|---|
| A) Next.js + SQLite | Full-stack React. SSR for fast loads, SQLite for local DB. Can deploy anywhere |
| B) SvelteKit + SQLite | Lighter than React, excellent performance. Smaller ecosystem |
| C) FastAPI (Python) + React SPA | Python backend matches src/ codebase. Separate frontend |
| D) Tauri + SvelteKit | Native desktop app with web tech. Excellent performance, but no web access |
Recommendation: Option C — Python backend aligns with existing src/ codebase, React frontend for rich UI. SQLite or PostgreSQL for metadata.
Decision:
2. Mobile Strategy
Question: How to handle phone/tablet access?
| Option | Description |
|---|---|
| A) PWA (Progressive Web App) | Responsive web app installable on phone. Single codebase, works offline |
| B) React Native | Native mobile app. Better UX but separate codebase |
| C) Responsive web only | Just a website, no install. Simplest but no offline |
Recommendation: Option A — PWA gives native-like experience with single codebase.
Decision:
3. Hosting
Question: Where does this run?
| Option | Description |
|---|---|
| A) Local only | Runs on laptop, access via LAN. No internet needed |
| B) VPS (ties into FR-019) | Hosted on VPS, accessible from anywhere. Needs auth |
| C) Hybrid | Local-first with optional cloud sync |
Recommendation: Option B — VPS deployment enables phone access from anywhere. Ties into FR-019.
Decision:
Phase Overview
| Phase | Description | Status |
|---|---|---|
| Phase 1 | Core architecture: API + vault reader + basic UI shell | — |
| Phase 2 | Key views: feature dashboard, inbox, quick capture | — |
| Phase 3 | Mobile optimization (PWA), offline support | — |
| Phase 4 | Advanced: search, briefings view, chat interface | — |
| Phase 5 | Real-time: file watcher, live updates, notifications | — |
Phase 1: Core Architecture —
Goal: API that reads/writes the Markdown vault, basic UI shell with navigation.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
src/opus/ui/api/vault.py | Vault reader: parse Markdown + frontmatter | opus | — |
src/opus/ui/api/routes.py | REST API endpoints (list files, read, write, search) | opus | — |
src/opus/ui/api/db.py | SQLite metadata index (frontmatter fields, tags) | opus | — |
src/opus/ui/api/sync.py | File watcher → DB sync | opus | — |
src/opus/ui/frontend/ | React app scaffold with routing | opus | — |
Phase 2: Core Views —
Goal: Purpose-built views for the most-used Opus workflows.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
| Feature dashboard | Kanban-style view of feature lifecycle | opus | — |
| Inbox view | Quick capture + inbox items with actions | opus | — |
| File editor | Markdown editor with frontmatter support | opus | — |
| Search | Full-text search across vault | opus | — |
Prerequisites / Gap Analysis
Requirements
| Requirement | Description |
|---|---|
| REQ-1 | Python backend (FastAPI) |
| REQ-2 | Markdown parser with frontmatter support |
| REQ-3 | File system watcher for live sync |
| REQ-4 | Auth layer for remote access |
Current State
| Component | Status | Details |
|---|---|---|
| Vault structure | done | Well-defined Markdown structure with frontmatter |
| Python src/ | — | Not yet started (FR-009) |
| VPS | — | Not yet deployed (FR-019) |
Gap (What’s missing?)
| Gap | Effort | Blocker? |
|---|---|---|
| Python project scaffold | Medium | Yes (FR-009) |
| VPS for remote access | Medium | No (can run locally first) |
| Auth system | Low | No (single-user initially) |
Test
Manual tests
| Test | Expected | Actual | Last |
|---|---|---|---|
| API returns vault file list | JSON array of files with metadata | pending | - |
| Edit file via UI and verify .md updated | Markdown file reflects changes | pending | - |
| Mobile PWA installable | App installs on phone | pending | - |
AI-verified tests
| Scenario | Expected behavior | Verification method |
|---|---|---|
| … | … | … |
E2E tests
| Scenario | Assertion |
|---|---|
| … | … |
Integration tests
| Component | Coverage |
|---|---|
| … | … |
Unit tests
| Component | Tests | Coverage |
|---|---|---|
| … | … | … |
History
| Date | Event | Details |
|---|---|---|
| 2026-03-16 | Created | User wants custom UI to replace Obsidian across all devices |
References
- FR-019 (VPS Deployment) — hosting dependency
- FR-009 (Python Project Scaffold) — backend dependency