Inboxintel/docs/discovery/01-architecture-review.md

# 01 — Architecture Review (current state)

Phase 1 deliverable: a grounded assessment of InboxIntel as it exists today, from the
source. This is the baseline the redesign builds on.

## Architecture
**Clean Architecture, .NET 8** — strict dependency rule `Api → Infrastructure → Application → Domain`.

| Layer | Responsibility | Key contents |
|-------|----------------|--------------|
| **Domain** | Entities + enums, no external deps | `Email`, `Sender`, `Domain`, `MailThread`, `Label`/`EmailLabel`, `Attachment`; `EmailCategory` |
| **Application** | Interfaces, DTOs, validation, parsing | `ISearchService` et al., `GmailQueryParser`, FluentValidation |
| **Infrastructure** | EF Core/Npgsql, integrations, workers | `SearchService`, `CleanupService`, `AnalyticsService`, `HeuristicClassifier`, **AI providers**, exports, `GmailSyncWorker`, `DigestWorker` |
| **Api** | ASP.NET Core Web API | Thin controllers, DI, Serilog, OAuth |
| **Frontend** | React 18 + Vite SPA | Chart.js, react-grid-layout (draggable dashboard), Tailwind |

- **Data:** PostgreSQL (EF Core + Npgsql). `Email` designed for 100k+ rows/user; a
  **generated `tsvector`** column backs full-text search.
- **Background:** hosted workers — `GmailSyncWorker` (scheduled sync), `DigestWorker` (digest).
- **AI seam (already present):** `IAiProvider` with `NullAiProvider` (disabled),
  `OllamaProvider` (local `/api/chat`), `OpenAiProvider` (cloud). Contract today is a
  single `CompleteAsync(systemPrompt, userPrompt)`.
- **Security:** Google OAuth2 (read-only Gmail), cookie session + JWT, refresh tokens
  encrypted via Data Protection API, **IDOR-safe global query filters**, SSRF egress
  guard, non-root containers, destructive actions require `Confirmed` + server preview.
- **Delivery:** Docker Compose (Postgres/API/frontend/optional nginx) + Gitea CI/CD.

## Feature set
Gmail connect + sync → Postgres · analytics dashboard (draggable widgets) · advanced
search (Gmail operators + FTS) · safe bulk cleanup · unsubscribe management
(List-Unsubscribe / one-click) · heuristic categorisation (smart folders) · exports
(PDF/CSV/JSON) · optional **advisory** AI · sender/domain aggregation.

## Existing search implementation (flagship)
1. **`GmailQueryParser`** (Application) parses `from: to: domain: after: before:
   is:unread|read has:attachment`; remaining text → free-text.
2. **`SearchService`** (Infrastructure) composes structured filters as EF `WHERE`
   clauses, and free text via Postgres FTS:
   `SearchVector.Matches(PlainToTsQuery('english', term))`, where
   `SearchVector = to_tsvector('english', coalesce(Subject,'') || ' ' || coalesce(BodyText,''))`.
3. Results are per-user filtered (IDOR-safe), **ordered by `SentAtUtc DESC`**,
   offset-paginated, projected to `EmailSummaryDto`.

## Strengths
- Clean, testable layering; DI throughout; 39 tests + CI/CD gate.
- **Real Postgres FTS** (generated tsvector), not naïve `LIKE`.
- Security-forward (IDOR filters, encrypted tokens, SSRF guard, confirmed destructive ops).
- **AI already decoupled behind `IAiProvider`** — the "no-AI / Ollama / future" requirement is architecturally seeded.
- Read-only scope + advisory AI = privacy-respecting.

## Weaknesses
- **Search is single-mode**: ordered by **date, not relevance** (no `ts_rank`); no
  fuzzy/typo tolerance, no semantic/vector search, no grouping, no "why matched," no
  saved/recent/suggested searches.
- FTS is **English-only** and covers **only Subject + Body** (not sender, attachment
  names, labels).
- Sender/domain filters use `.Contains()` → **non-sargable ILIKE scans** (no `pg_trgm`).
- Category is a **single heuristic enum** — no multi-label, confidence, or learning.
- **`IAiProvider` is chat-only** — no embeddings/classification/extraction contract, so
  semantic search & structured extraction can't yet be expressed.
- Threading (`ThreadId`) exists but isn't surfaced as conversation intelligence.

## Technical debt
- EF global-query-filter vs required `Email↔EmailLabel` relationship warning (in logs).
- Hardcoded English FTS config.
- **678 KB single JS chunk** (no code-splitting) — cold-load cost.
- Relevance-blind ordering.
- AI interface too narrow for the roadmap.

## Performance bottlenecks
- `.Contains()` sender/domain → sequential scans (need `pg_trgm` GIN indexes).
- **Offset pagination** (`Skip/Take` + `Count`) degrades on deep pages → keyset/cursor.
- No score-based top-N (no ranking) → sorts full match set by date.
- Single JS chunk (~219 KB gzip) slows cold loads.
- Full-mailbox sync latency at 100k+ (batching/Polly present, but per-message fetch).

## Documentation quality
Strong for a scaffold: `README`, `docs/ARCHITECTURE.md`, OAuth setup, `docs/specs/*`,
`AGENTS.md`, plus `WORKFLOW.md`/`CHANGELOG`; meaningful XML-doc comments.
**Gaps:** no API reference, no ERD/data-model doc, no ADRs, no search/AI design docs —
which this discovery produces.

## Verdict
A clean, secure, well-tested foundation with a **genuine FTS base** and an **AI seam
already in place**. The biggest opportunities are exactly where the product wants to
win: **relevance-ranked, multi-mode, assisted search**; a **richer AI contract**
(embeddings/classification/extraction); **conversation intelligence**; and a **modern,
approachable UX**. None of these require a rewrite — they extend the existing seams.