A search interface for Polish PKD activity codes — describe what your business does, get the matching codes
In development since February 2025
The pain it solves
Anyone registering a business in Poland has to pick PKD codes — a five-digit classification of what your business does. There are over 600 of them, the official catalogue is a PDF that nobody reads end-to-end, and picking the wrong code means corrections at the tax office later. The de-facto workflow is: open a search engine, type approximately what your business does, scroll forum posts to figure out which codes apply.
Pkd Search replaces that workflow with one search box. Type "I run a coffee shop with a small bakery", get a ranked list of relevant codes with their official descriptions and notes about what they cover.
⚙️ How It Works
The frontend is a Vite-built React app. The search box debounces the user's query, sends it to a backend (separate repo, pkd-search-backend) that runs the query through an embedding model, looks up nearest neighbours in a vector index of the entire PKD 2007 catalogue, and returns ranked results.
Each result card shows the code, the official short name, the official long description, and any notes about what the code does and does not cover. Click a card to expand the full text; star it to add to a "my codes" list that's saved in localStorage; click "share" to generate an Open Graph preview image (via Vercel OG) of the selected codes for posting in Slack or to a colleague.
✨ Key Features
- Natural-language search over the full PKD 2007 catalogue — "I run a coffee shop", "online consulting for medical clinics", "construction subcontractor for finishing work".
- Ranked results with official short name, long description, and exclusion notes.
- Saved-codes list (per-device, localStorage) with copy-as-list export.
- Open Graph image generation via @vercel/og — pretty cards for sharing a code selection.
- Mobile-first design, three-pane on desktop (query / list / detail).
- Smooth motion via framer-motion on every transition — micro-interactions only, no spinning loaders.
- Result deep-linking through React Router (
/codes/74.10.Zopens the detail view directly). - Helmet-based SEO with per-code meta tags so individual codes show up in search engines.
- Lucide icon set for everything except the PKD code badges.
🛠️ Tech Stack
| Category | Stack |
|---|---|
| Framework | React 18 with Vite for dev / build |
| Routing | react-router-dom 6 |
| Data | axios with a small in-memory cache + AbortController-based query cancellation |
| Animations | framer-motion |
| Icons | lucide-react |
| OG images | @vercel/og |
| SEO | react-helmet-async |
| Hosting | Vercel (frontend), separate backend on Railway |
Decisions worth noting
Vector search over keyword search was the obvious right call. PKD codes are written in formal legal Polish — "działalność związana z wytwarzaniem niewrażliwych elementów kontrolnych" — which nobody types into a search box. Embedding-based similarity bridges the gap between "how the user thinks about their business" and "how the official code is worded".
The choice not to require sign-up was also deliberate. The whole app is a search-and-leave tool. Saved codes live in localStorage; if you clear your browser data you lose them, which the UI acknowledges with a small note. Adding accounts would have meant adding a backend complexity the product doesn't need.
The OG image feature came from a single user request and ended up driving most of the inbound traffic. Someone asks in a Slack channel "what PKD do I need for X?", a colleague sends back a Pkd Search link with three codes selected, the link previews as a clean image with the codes, and click-through is much higher than text alone. Cheap to build, large lift in word-of-mouth.
Status
The frontend is live and stable. The backend (vector index + embedding service) runs on Railway with a small Postgres + pgvector instance. Updating the catalogue requires re-embedding, which is a one-shot script when the official PKD revision lands; otherwise the system is hands-off.
Pkd Search is a React + Vite frontend that helps Polish entrepreneurs find the correct PKD (Polska Klasyfikacja Działalności) activity codes for company registration. It pairs a natural-language search box with a vector-search backend, displays ranked results with their official descriptions, and surfaces visual context with framer-motion animations. Highlights include semantic search over the entire PKD 2007 catalogue, share-to-OG-image generation via Vercel OG, mobile-first UI, and a caching layer that keeps repeat queries instant. Built with React, Vite, Tailwind, framer-motion, axios, and Vercel OG. In development since February 2025.