# riddhimaan-senapati/recuvia architecture

> Architecture diagram of the GitHub repository riddhimaan-senapati/recuvia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/riddhimaan-senapati/recuvia
- Repository: https://github.com/riddhimaan-senapati/recuvia

## Overview

Recuvia helps people report found belongings and search for lost items using text or images, then review similarity-ranked matches. Its main workflow embeds a query with CLIP, searches item vectors in Supabase, and displays matching item details; clicking an item can launch a similar-item search. Reporting requires authentication and stores an image plus item metadata and its embedding. The README documents Google OAuth, adjustable thresholds/result counts, and deletion. Some page-to-component wiring and database implementation details were not sampled, so those connections are shown only where documented or evidenced.

Main entry points: [`frontend/app/utils/supabase.ts`](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/utils/supabase.ts) (Vector data helpers), [`frontend/hooks/useSearch.ts`](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/hooks/useSearch.ts) (Search actions), [`frontend/app/api/upload/route.ts`](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/api/upload/route.ts) (Upload route), [`frontend/app/api/search/text/route.ts`](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/api/search/text/route.ts) (Text search route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_home["Landing page<br/>[page.tsx]"]
  node_dashboard["Search dashboard<br/>[page.tsx]"]
  node_searchui["Search panel<br/>[SearchPanel.tsx]"]
  node_results["Match results<br/>[ResultsGrid.tsx]"]
  node_searchhook["Search actions<br/>[useSearch.ts]"]
  node_uploadui["Found item form<br/>[UploadForm.tsx]"]
  node_uploadhook["Upload actions<br/>[useUpload.ts]"]
end

subgraph group_routes["API workflows"]
  node_textsearch["Text search route<br/>[route.ts]"]
  node_imagesearch["Image search route<br/>[route.ts]"]
  node_uploadroute["Upload route<br/>[route.ts]"]
  node_deleteroute["Delete route<br/>[route.ts]"]
end

subgraph group_services["Embedding and data"]
  node_embeddings["CLIP embeddings<br/>[embeddings.ts]"]
  node_dbhelpers["Vector data helpers<br/>[supabase.ts]"]
  node_supabaseclient["Supabase clients<br/>[supabase-server.ts]"]
end

subgraph group_identity["Identity"]
  node_authpages["Sign-in and signup"]
  node_authshell["Auth form<br/>[AuthShell.tsx]"]
  node_authcontext["Session context<br/>[AuthContext.tsx]"]
  node_authroute["OAuth callback<br/>[page.tsx]"]
end

node_visitor(("Visitor"))
node_clip["CLIP model"]
node_postgres[("Supabase Postgres")]
node_storage[("Supabase Storage")]
node_supaauth["Supabase Auth"]

node_visitor -->|"opens"| node_home
node_home -->|"navigates"| node_dashboard
node_dashboard -->|"renders"| node_searchui
node_searchui -->|"uses"| node_searchhook
node_searchhook -->|"posts query"| node_textsearch
node_searchhook -->|"posts image"| node_imagesearch
node_textsearch -->|"embeds text"| node_embeddings
node_imagesearch -->|"embeds image"| node_embeddings
node_embeddings -->|"runs inference"| node_clip
node_textsearch -->|"searches vector"| node_dbhelpers
node_imagesearch -->|"searches vector"| node_dbhelpers
node_dbhelpers -->|"queries matches"| node_postgres
node_textsearch -->|"returns matches"| node_results
node_imagesearch -->|"returns matches"| node_results
node_searchhook -->|"posts similar query"| node_textsearch
node_dashboard -->|"renders"| node_uploadui
node_uploadui -->|"uses"| node_uploadhook
node_uploadhook -->|"posts item"| node_uploadroute
node_uploadroute -->|"creates session client"| node_supabaseclient
node_uploadroute -->|"stores image"| node_storage
node_uploadroute -->|"embeds image"| node_embeddings
node_uploadroute -->|"inserts item"| node_dbhelpers
node_dbhelpers -->|"writes item"| node_postgres
node_searchhook -->|"requests deletion"| node_deleteroute
node_deleteroute -->|"deletes item"| node_dbhelpers
node_deleteroute -->|"deletes image"| node_storage
node_visitor -->|"opens account"| node_authpages
node_authpages -->|"renders form"| node_authshell
node_authcontext -->|"checks session"| node_supaauth
node_authpages -->|"authenticates"| node_supaauth
node_authroute -->|"completes OAuth"| node_supaauth

click node_home "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/page.tsx"
click node_dashboard "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/main/page.tsx"
click node_searchui "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/components/SearchPanel.tsx"
click node_results "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/components/ResultsGrid.tsx"
click node_searchhook "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/hooks/useSearch.ts"
click node_uploadui "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/components/UploadForm.tsx"
click node_uploadhook "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/hooks/useUpload.ts"
click node_authpages "https://github.com/riddhimaan-senapati/recuvia/tree/main/frontend/app/auth"
click node_authshell "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/components/AuthShell.tsx"
click node_authcontext "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/contexts/AuthContext.tsx"
click node_authroute "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/auth/callback/page.tsx"
click node_textsearch "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/api/search/text/route.ts"
click node_imagesearch "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/api/search/image/route.ts"
click node_uploadroute "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/api/upload/route.ts"
click node_deleteroute "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/api/delete/route.ts"
click node_embeddings "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/utils/embeddings.ts"
click node_dbhelpers "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/utils/supabase.ts"
click node_supabaseclient "https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/utils/supabase-server.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_dashboard,node_searchui,node_results,node_searchhook,node_uploadui,node_uploadhook toneBlue
class node_textsearch,node_imagesearch,node_uploadroute,node_deleteroute,node_postgres,node_storage toneAmber
class node_embeddings,node_dbhelpers,node_supabaseclient toneMint
class node_authpages,node_authshell,node_authcontext,node_authroute toneRose
class node_visitor,node_clip,node_supaauth toneIndigo
```

## Components

### User experience

- [Landing page](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Search dashboard](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/main/page.tsx): `frontend/app/main/page.tsx`
- [Search panel](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/components/SearchPanel.tsx): `frontend/components/SearchPanel.tsx`
- [Match results](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/components/ResultsGrid.tsx): `frontend/components/ResultsGrid.tsx`
- [Search actions](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/hooks/useSearch.ts): `frontend/hooks/useSearch.ts`
- [Found item form](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/components/UploadForm.tsx): `frontend/components/UploadForm.tsx`
- [Upload actions](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/hooks/useUpload.ts): `frontend/hooks/useUpload.ts`

### API workflows

- [Text search route](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/api/search/text/route.ts): `frontend/app/api/search/text/route.ts`
- [Image search route](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/api/search/image/route.ts): `frontend/app/api/search/image/route.ts`
- [Upload route](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/api/upload/route.ts): `frontend/app/api/upload/route.ts`
- [Delete route](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/api/delete/route.ts): `frontend/app/api/delete/route.ts`

### Embedding and data

- [CLIP embeddings](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/utils/embeddings.ts): `frontend/app/utils/embeddings.ts`
- [Vector data helpers](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/utils/supabase.ts): `frontend/app/utils/supabase.ts`
- [Supabase clients](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/utils/supabase-server.ts): `frontend/app/utils/supabase-server.ts`

### Identity

- [Sign-in and signup](https://github.com/riddhimaan-senapati/recuvia/tree/main/frontend/app/auth): `frontend/app/auth`
- [Auth form](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/components/AuthShell.tsx): `frontend/components/AuthShell.tsx`
- [Session context](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/contexts/AuthContext.tsx): `frontend/contexts/AuthContext.tsx`
- [OAuth callback](https://github.com/riddhimaan-senapati/recuvia/blob/main/frontend/app/auth/callback/page.tsx): `frontend/app/auth/callback/page.tsx`

### Other components

- **Visitor**
- **CLIP model**
- **Supabase Postgres**
- **Supabase Storage**
- **Supabase Auth**

## Connections

- Visitor → Landing page: opens
- Landing page → Search dashboard: navigates
- Search dashboard → Search panel: renders
- Search panel → Search actions: uses
- Search actions → Text search route: posts query
- Search actions → Image search route: posts image
- Text search route → CLIP embeddings: embeds text
- Image search route → CLIP embeddings: embeds image
- CLIP embeddings → CLIP model: runs inference
- Text search route → Vector data helpers: searches vector
- Image search route → Vector data helpers: searches vector
- Vector data helpers → Supabase Postgres: queries matches
- Text search route → Match results: returns matches
- Image search route → Match results: returns matches
- Search actions → Text search route: posts similar query
- Search dashboard → Found item form: renders
- Found item form → Upload actions: uses
- Upload actions → Upload route: posts item
- Upload route → Supabase clients: creates session client
- Upload route → Supabase Storage: stores image
- Upload route → CLIP embeddings: embeds image
- Upload route → Vector data helpers: inserts item
- Vector data helpers → Supabase Postgres: writes item
- Search actions → Delete route: requests deletion
- Delete route → Vector data helpers: deletes item
- Delete route → Supabase Storage: deletes image
- Visitor → Sign-in and signup: opens account
- Sign-in and signup → Auth form: renders form
- Session context → Supabase Auth: checks session
- Sign-in and signup → Supabase Auth: authenticates
- OAuth callback → Supabase Auth: completes OAuth