LandFind — AI-Native Lost & Found Recovery OS

A production-grade, agentic recovery operating system powered by multimodal AI.
Built on three immutable primitives: FIND, SORT, REPORT.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                   Next.js Frontend (v15)                        │
│   Auth │ Dashboard │ Reports │ Items │ Matches │ Claims │ Admin │
├─────────────────────────────────────────────────────────────────┤
│                  FastAPI Gateway (v1) + WebSocket                │
│  /auth /reports /items /matches /claims /signals /uploads /admin │
├─────────────────────────────────────────────────────────────────┤
│               LangGraph Agent Orchestrator                      │
│  ┌──────────┬──────────┬──────────┬──────────┬─────────────┐   │
│  │  Vision  │  Signal  │ Matching │  Claim   │Notification │   │
│  │  Agent   │  Agent   │  Agent   │  Agent   │   Agent     │   │
│  └──────────┴──────────┴──────────┴──────────┴─────────────┘   │
├─────────────────────────────────────────────────────────────────┤
│                      Service Layer                              │
│  CLIP Embedding │ Qdrant Vector Store │ Vision │ Perceptual Hash│
│  Matching Engine│ S3 Storage │ WS Manager │ Signal Ingestion    │
├──────────┬──────┬───────┬──────┬───────┬──────┬────────────────┤
│ Postgres │Qdrant│ Redis │MinIO │ OTel  │Jaeger│  Edge IoT GW   │
└──────────┴──────┴───────┴──────┴───────┴──────┴────────────────┘

Quick Start

Prerequisites

• Python 3.11+
• Node.js 20+
• Docker & Docker Compose
• (Optional) NVIDIA GPU for accelerated CLIP inference

1. Clone & Configure

cp .env.example .env
# Edit .env — add your OpenAI API key

2. Start Infrastructure

docker compose -f docker/docker-compose.yml up -d

Services: PostgreSQL 16, Qdrant 1.13, Redis 7, MinIO (S3)

3. Install Backend

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
alembic upgrade head
uvicorn app.main:app --reload --port 8000

4. Install Frontend

cd frontend
npm install
npm run dev

5. Access

Service	URL
Frontend	http://localhost:3000
API Docs	http://localhost:8000/docs
MinIO Console	http://localhost:9001
Qdrant UI	http://localhost:6333/dashboard

One-command dev start

./scripts/dev.sh

Project Structure (99 files)

backend/                         # Python API + AI agents
├── app/
│   ├── agents/                  # LangGraph agent nodes
│   │   ├── orchestrator.py      # Recovery pipeline state graph
│   │   ├── vision_agent.py      # Image → CLIP embedding + attributes
│   │   ├── signal_agent.py      # IoT/BLE/NFC correlation
│   │   ├── matching_agent.py    # Multi-signal FIND scoring
│   │   ├── claim_agent.py       # Verification challenge + evaluation
│   │   ├── notification_agent.py# WebSocket push + in-app alerts
│   │   └── state.py             # Typed state definition
│   ├── api/v1/routes/           # FastAPI endpoints
│   │   ├── auth.py              # Register, login, profile, password
│   │   ├── reports.py           # Lost-item CRUD + pipeline trigger
│   │   ├── items.py             # Found-item CRUD + reverse matching
│   │   ├── matches.py           # View, confirm, reject matches
│   │   ├── claims.py            # Submit, verify, staff review
│   │   ├── signals.py           # IoT event ingestion (single + batch)
│   │   ├── uploads.py           # Presigned S3 URLs + confirm
│   │   ├── admin.py             # Stats, user mgmt, bulk ops
│   │   ├── ws.py                # Authenticated WebSocket endpoint
│   │   └── health.py            # Health/readiness probes
│   ├── core/                    # Security (JWT, bcrypt), observability (OTel), exceptions
│   ├── db/                      # Async SQLAlchemy sessions + repositories
│   ├── models/                  # 6 ORM entities (User, LostReport, FoundItem, Match, Claim, Signal)
│   ├── schemas/                 # Pydantic v2 request/response contracts
│   ├── services/                # Embedding, vector store, vision, matching, S3 storage, WS manager
│   └── workers/                 # Background task processors
├── tests/                       # Pytest (unit + integration)
├── alembic/                     # Database migrations
└── pyproject.toml

frontend/                        # Next.js 15 + React 19 + Tailwind CSS 4
├── src/
│   ├── app/                     # Pages: auth, dashboard, reports, items, matches, claims, admin
│   ├── components/              # UI primitives (Button, Input, Card, Badge) + layout (Sidebar, Header)
│   ├── hooks/                   # useWebSocket (auto-reconnecting WS client)
│   ├── lib/                     # API client, Zustand stores, utilities
│   └── types/                   # TypeScript type definitions
└── package.json

docker/
├── docker-compose.yml           # Postgres, Qdrant, Redis, MinIO, OTel, Jaeger
└── Dockerfile.backend

Agent Topology

Recovery Pipeline (LangGraph)

Vision → [Signal?] → Matching → [Notification?] → END

• Vision Agent: CLIP embedding + pHash + LLM attribute extraction
• Signal Agent: IoT/BLE/NFC correlation (conditional, only if identifiers present)
• Matching Agent: k-NN vector search + 6-dimensional scoring
• Notification Agent: WebSocket push to connected clients

Claim Verification Pipeline (LangGraph)

Generate Challenges → [Evaluate Answers?] → END

• Category-adaptive challenge generation (electronics, bags, documents, pets, etc.)
• LLM-powered answer evaluation with structured scoring
• Automatic approve/reject/manual_review decision thresholds

Matching Algorithm

Composite confidence across six signal dimensions:

Signal	Weight	Source
Visual Similarity	0.30	CLIP cosine distance
Text Similarity	0.25	CLIP text embeddings
Spatial Proximity	0.15	Haversine distance decay
Temporal Proximity	0.10	Exponential time decay
Perceptual Hash	0.10	Hamming distance on pHash
IoT Signal Match	0.10	BLE/NFC/RFID correlation

API Surface

Method	Endpoint	Auth	Description
POST	/api/v1/auth/register	Public	Create account
POST	/api/v1/auth/login	Public	Get JWT token
GET	/api/v1/auth/me	User	Current user profile
POST	/api/v1/reports	User	Submit lost-item report
GET	/api/v1/reports	User	List lost reports
POST	/api/v1/items	User	Ingest found item
GET	/api/v1/items	User	List found items
GET	/api/v1/matches/report/:id	User	Matches for a report
POST	/api/v1/claims	User	Submit claim + get challenges
POST	/api/v1/claims/:id/verify	User	Submit verification answers
PATCH	/api/v1/claims/:id/review	Staff	Staff review override
POST	/api/v1/uploads/presign	User	Get presigned S3 upload URL
POST	/api/v1/uploads/confirm	User	Confirm upload + trigger vision
POST	/api/v1/signals	API Key	Ingest IoT signal event
POST	/api/v1/signals/batch	API Key	Batch signal ingestion
GET	/api/v1/admin/stats	Staff	Platform-wide statistics
GET	/api/v1/admin/users	Staff	List all users
GET	/api/v1/admin/claims/queue	Staff	Pending claim review queue
WS	/api/v1/ws?token=JWT	User	Real-time notification channel
GET	/health	Public	Health probe
GET	/ready	Public	Readiness probe

Technology Stack

Layer	Technology
Frontend	Next.js 15, React 19, Tailwind CSS 4, Zustand
API Framework	FastAPI + Uvicorn
Agent System	LangGraph (multi-agent orchestration)
Embeddings	OpenCLIP (ViT-L/14, 768-dim)
Vector DB	Qdrant (HNSW + INT8 scalar quantization)
Vision LLM	GPT-4o (attribute extraction + claim verify)
Database	PostgreSQL 16 + SQLAlchemy 2.0 (async)
Cache/Queue	Redis 7
Object Storage	MinIO / S3 (presigned upload flow)
Real-time	WebSocket (authenticated, auto-reconnect)
Observability	OpenTelemetry + structlog + Jaeger
Auth	JWT (HS256) + bcrypt + RBAC (user/staff/admin)

Running Tests

cd backend
pytest -m unit          # Fast unit tests (no external deps)
pytest -m integration   # Requires running infrastructure
pytest --cov=app        # With coverage

License

Proprietary — All rights reserved.