# Home Information Vault — Implementation Roadmap

## 1. Vision & Scope
A single, secure place for every household to store rarely-needed but mission-critical information ("digital junk drawer"). Once data lives here, switching away is painful, driving long-term retention.

**Primary user stories**
1. _As a household member_, I can add, view, and update structured facts (e.g. Wi-Fi password, paint colours).
2. _As a household member_, I can upload and annotate documents (leases, insurance certificates, receipts).
3. _As a household member_, I receive proactive reminders for expiring warranties/documents.
4. _As a guest_, I can quickly get the Wi-Fi password via a one-tap share link or QR code.

## 2. Data Model (SQLAlchemy)
| Model | Fields | Notes |
|-------|--------|-------|
| `VaultCategory` | `id`, `group_id`, `name`, `icon` | Logical grouping ("Warranties", "Home Info", "Secure Docs") |
| `VaultEntry` | `id`, `group_id`, `category_id`, `title`, `description`, `data` (JSONB), `reminder_at` (DateTime), `created_by_id`, `created_at`, `updated_at`, `is_deleted` | Generic row powering all entry types |
| `VaultAttachment` | `id`, `entry_id`, `file_path`, `file_type`, `file_size`, `thumbnail_path` | S3 / local MinIO storage |
| `VaultShareToken` | `id`, `entry_id`, `token`, `expires_at`, `created_at` | For guest Wi-Fi share links |

*Use `SoftDeleteMixin` everywhere to support undos.*

## 3. API Design (FastAPI v1)
*All routes require group membership (reuse `GroupMemberDependency`).*

```
POST   /vault/categories                 → create category
GET    /vault/categories                 → list categories
POST   /vault/entries                    → create entry
GET    /vault/entries?category_id=       → list entries
GET    /vault/entries/{id}               → retrieve entry
PUT    /vault/entries/{id}               → update entry
DELETE /vault/entries/{id}               → soft-delete entry
POST   /vault/entries/{id}/attachments   → upload file (multipart)
DELETE /vault/attachments/{id}           → remove file
POST   /vault/entries/{id}/share         → generate share token (Wi-Fi)
GET    /vault/share/{token}              → public redirect or JSON payload
```

## 4. Services & Background Jobs
1. **OCR & Manual Fetcher**  
   – When a `VaultEntry` is created in the "Warranties & Manuals" category with an appliance model number or image, trigger Celery task:  
   a. Run OCR to extract model no.  
   b. Scrape/search manufacturer manuals online.  
   c. Upload PDF into `VaultAttachment`.
2. **Reminder Scheduler**  
   – Nightly job checks `reminder_at` ≤ now; for each match push notification & e-mail via existing notification system.

## 5. Permission Model
- **Group roles**: `owner` ↔ full access; `member` ↔ CRUD but cannot delete categories; guests only via share token.
- Share tokens are read-only, time-limited, no authentication.

## 6. Front-End (Vue 3 / Pinia)
### Routes
- `/vault` → Category list (cards)
- `/vault/:categoryId` → Entry table/list
- `/vault/entry/:id` → Detail & edit sheet/dialog

### Components
- `VaultCategoryCard.vue`
- `VaultEntryList.vue` (virtual scrolling)
- `VaultEntryForm.vue` (dynamic fields per category)
- `VaultAttachmentViewer.vue`
- `WifiShareDialog.vue` (QR + copy button)

### Store
`useVaultStore` with actions: `fetchCategories`, `fetchEntries`, `createEntry`, … Similar pattern to lists/expenses.

### UX Polishes
- Drag-&-drop file uploads, inline previews.
- Badge showing upcoming expirations.

## 7. Security & Compliance
- Encrypt sensitive file storage at rest (S3 SSE-KMS / local).  
- Mask secrets (Wi-Fi, account numbers) until eye icon toggled.  
- Audit log (`FinancialAuditLog` style) for every change.

## 8. Migration Plan
1. Alembic migration to create `vault_*` tables.  
2. Seed default categories for existing groups.  
3. Deploy backend.  
4. Roll out UI hidden behind feature flag → beta groups.  
5. Gather feedback, iterate, GA.

## 9. Estimated Timeline
| Phase | Duration | Deliverables |
|-------|----------|--------------|
| DB & API scaffold | 2 w | Models, CRUD routes, tests |
| Attachments + S3 | 1 w | Upload service, presigned URLs |
| OCR + Manual fetch | 1 w | Celery tasks, unit tests |
| Front-end MVP | 2 w | Category & Entry CRUD screens |
| Reminders & share links | 1 w | Scheduler, share token endpoints |
| Polish & Beta | 1 w | UX, accessibility, docs |

_Total ≈ 8 weeks with 1 backend + 1 frontend engineer._

## 10. Compatibility with Existing Codebase

### 10.1 Backend Alignment
- **Database Session & Dependency Injection**: Use the shared `get_db` dependency from `app.db.session` just like current CRUD routers (see `lists`, `groups`).
- **Router Pattern**: Follow `/app/api/v1/endpoints/` structure.  Create `vault.py` with `router = APIRouter(prefix="/vault", tags=["Vault"])` mirroring `lists.py` implementation.
- **CRUD Layer**: Add `crud/vault_entry.py`, `crud/vault_category.py`, etc., inheriting from `CRUDBase` pattern already used across the project.
- **Schemas**: Place Pydantic models in `schemas/vault.py`, version with `BaseModelOrm` to enable `.from_orm()` like others.
- **Soft Deletes**: Reuse `SoftDeleteMixin` and central `query_active()` helper so filters are consistent.
- **Permissions**: Reuse `GroupAccessChecker` dependency (currently used in `items`, `expenses`) ensuring RBAC is enforced uniformly.
- **File Uploads**: Leverage existing S3 service in `core/` (if none, extend minimal wrapper) used by OCR.
- **Background Tasks**: Hook Celery tasks into `jobs/` package; scheduler already exists for recurring expenses – add periodic task entry to same Beat schedule.

### 10.2 Front-End Alignment
- **API Layer**: Extend `services/api.ts` with `vault` endpoints; follow pattern of `groupService.ts` and `expenseService.ts` for generated functions.
- **State Management**: Implement `stores/vaultStore.ts` mirroring `listDetailStore.ts` (getters for categories, entries, attachments) using Pinia & optimistic updates helpers already present.
- **Routing**: Add vault routes to `router/routes.ts`, lazy-load components like existing pages. Example:
  ```ts
  {
    path: '/vault',
    name: 'VaultHome',
    component: () => import('@/pages/VaultPage.vue'),
  }
  ```
- **i18n**: Add placeholder strings under `i18n/en.json` etc.
- **UI Components**: Conform to existing design system: reuse `ui/Card.vue`, `Dialog.vue`, `Button.vue`; mount in `layouts/MainLayout.vue` nav with new icon.
- **Auth Handling**: Vault routes guard with existing `useAuthStore().isAuthenticated` redirecting to `/auth/login` if needed.

### 10.3 Testing Strategy
- **Backend**: Parametrised pytest cases similar to `tests/api/v1/endpoints/test_lists.py`. Fixture: create group + user, test CRUD and share link token.
- **Frontend**: Vitest + Testing-Library component tests; e2e via Playwright (similar to `lists.spec.ts`).

---

_This ensures the Vault integrates seamlessly without reinventing infrastructure._
