vault / rules

---
description: Core file-system logic stays UI-agnostic; platform-specific quirks stay behind an adapter per OS
alwaysApply: false
---

# Architecture

Vault targets multiple operating systems (macOS + Windows, at minimum) with a single shared UI.
Stack: Wails v3 (Go backend + native webview) + React/TypeScript/Tailwind frontend. Full design
spec: `docs/SPEC.md`.

```
main.go                    ← Wails app entry: window, theming, service registration
internal/core/             ← platform-neutral: dir listing, metadata, search/frecency index,
                              file ops (copy/move/rename), trash interface — no OS-specific APIs
        ▲
        │  a narrow, platform-neutral interface (paths, entries, watch events, operations)
        │
internal/platform/darwin/  ← macOS adapter: Trash, FSEvents watcher, path/permission quirks
internal/platform/windows/ ← Windows adapter: Recycle Bin, ReadDirectoryChangesW watcher, path quirks
internal/service/          ← thin Wails-bound service structs exposed to the frontend; call only
                              into internal/core, never straight into a platform adapter
frontend/                  ← React + TypeScript + Tailwind UI; talks only to internal/service
                              via generated Wails bindings
```

## Rules

| Do | Don't |
|----|-------|
| Keep file-system logic (list, search, sort, copy/move/delete) behind a small interface | Scatter OS-specific calls (`FSEvents`, `ReadDirectoryChangesW`, etc.) through the UI layer |
| Put OS-specific behavior (trash vs. recycle bin, path separators, case sensitivity, hidden-file conventions) in one adapter per OS | Special-case the OS inline across unrelated files with `if runtime.GOOS == ...`-style checks |
| Route destructive operations (delete, overwrite, move across volumes) through one reviewable code path | Duplicate delete/move logic per call site |
| Design the core interface so a new platform adapter can be added without touching the UI | Leak a platform adapter's types into shared UI code |

## Adding a feature (checklist)

1. **Failing unit test (TDD)** — see `unit-tests-tdd.mdc`.
2. **Core** — implement in the platform-neutral core; no OS-specific APIs here.
3. **Adapter** — if the feature needs OS-specific behavior, add/extend the adapter for that OS only.
4. **UI** — wire the UI to the core interface, not to the adapter directly.
5. **Other platforms** — confirm the feature degrades sensibly (or is stubbed clearly) on OSes
   without an adapter yet.