type-ah ✍️

A production-inspired search autocomplete system, built phase by phase — from a basic trie to a distributed, ranked, real-time suggestion engine.

Built as a learning project to implement the concepts behind large-scale autocomplete systems (Google, YouTube, Amazon) from the ground up.

---

Current Version — v0.2.0

Popularity-based ranking with a precomputed top-K trie, LRU cache, event ingestion, background rebuild scheduler, and a metrics endpoint.

---

Tech Stack

Layer	Technology
Backend	Java 17, Spring Boot 3.5
Data Structure	Trie with precomputed top-K per node
Caching	In-memory LRU (LinkedHashMap)
Frontend	React, Vite
Containerisation	Docker, Docker Compose
Linting / Formatting	ESLint, Prettier

---

Architecture

type-ah/
├── backend/                  # Spring Boot service
│   └── src/main/java/com/ayush/typeah/
│       ├── controller/       # AutocompleteController, EventController, MetricsController
│       ├── service/          # TrieService, FrequencyStore, SuggestionCache, TrieRebuildScheduler
│       ├── model/            # TrieNode, SearchEvent
│       └── loader/           # DataLoader
├── frontend/                 # React + Vite
│   └── src/
│       ├── components/       # SearchBox
│       └── App.jsx
└── docs/                     # Architecture diagrams, ADRs

At startup, DataLoader seeds the trie and FrequencyStore from queries.json with initial popularity scores, then runs a bottom-up pass to precompute top-K suggestions at every trie node. Each GET /api/v1/suggest request checks the LRU cache first — on a miss, it walks the trie and caches the result. User events (POST /api/v1/events) accumulate in FrequencyStore; every 60 seconds TrieRebuildScheduler rebuilds the trie with updated frequencies and atomically swaps the root pointer.

See docs/architecture-v0.2.0.md for full system and sequence diagrams.

---

Running Locally

Dev mode (recommended during development)

Backend — terminal 1:

cd backend
./mvnw spring-boot:run

Frontend — terminal 2:

cd frontend
npm run dev

Open http://localhost:5173

Docker (full stack)

docker compose up --build

Open http://localhost

docker compose down   # to stop

---

API

GET /api/v1/suggest

Returns top-K autocomplete suggestions ranked by popularity.

Parameter	Type	Required	Default	Description
prefix	string	✅	—	The search prefix
limit	int	❌	10	Max suggestions to return

Example:

curl "http://localhost:8080/api/v1/suggest?prefix=car&limit=5"

Response:

["car rental", "car insurance", "car wash near me", "cardigan", "cards against humanity"]

---

POST /api/v1/events

Records a search or click event. Updates the frequency store used by the next rebuild.

Request body:

{ "query": "cardigan", "type": "search" }

Response: 200 OK (empty body)

---

GET /api/v1/metrics

Returns cache and frequency store stats.

Example:

curl "http://localhost:8080/api/v1/metrics"

Response:

{
  "cache_size": 2,
  "cache_hits": 1,
  "cache_misses": 2,
  "cache_hit_rate_pct": 33.33,
  "frequency_store_size": 52
}

---

Running Tests

cd backend
./mvnw test

Tests run: 11, Failures: 0, Errors: 0

---

Roadmap

Version	Phase	Status
v0.1.0	Core Autocomplete	✅ Done
v0.2.0	Intelligent Ranking	✅ Done
v0.5.0	Production Foundation	🔜 Next
v0.7.0	Data Pipeline	⬜ Planned
v0.8.0	Distribution Layer	⬜ Planned
v1.0.0	Production-Ready	⬜ Planned

---

Docs

• docs/architecture-v0.1.0.md — v0.1.0 system diagram, sequence diagram, Docker topology
• docs/architecture-v0.2.0.md — v0.2.0 system diagram with ranking and cache layers
• docs/adr-001-rebuild-inconsistency.md — trie rebuild inconsistency window