feat: LinkedIn profile search engine (Django + React + Elasticsearch + ELK)

Full-stack implementation of the Cyberyan full-stack trial task.

Backend (Django 5 / DRF)
- Normalised PostgreSQL model (Profile, Company, School, Skill, Experience,
  Education) as the source of truth, with GIN + trigram indexes.
- Self-healing CSV reader: the supplied export carries an injected watermark
  column, missing columns, rows split by broken quoting and a duplicated
  header. A signature-scored Needleman-Wunsch alignment reconstructs 284 clean
  records out of 336 physical rows; only 10 rows parse correctly without it.
- Pluggable search layer (Strategy): Elasticsearch by default, PostgreSQL
  full-text search as a fallback selected by a single environment variable.
- Keyword search with per-field boosts, fuzziness and phrase boosting, six
  faceted filters (OR within a filter, AND across filters), an experience
  range, four sort orders, highlighting and facet aggregations.
- JWT auth with rotation + blacklist, three roles, PII masking, scoped rate
  limits, a single error envelope, OpenAPI schema and health probes.

Frontend (React 18 / TypeScript / Vite)
- Debounced search with type-ahead, faceted filter panel, result cards,
  profile drawer, URL-synced search state, automatic token refresh.
- Highlight snippets rendered without dangerouslySetInnerHTML.

Infrastructure
- Hardened multi-stage images (non-root, read-only rootfs, healthchecks).
- docker-compose for the full stack plus dev and production overlays.
- ELK: structured JSON logs shipped asynchronously to Logstash, routed per
  event type, with a composable index template and a Kibana setup script.

Quality
- 61 backend tests (85% coverage), ruff/black/bandit/mypy, ESLint + tsc,
  GitHub Actions running lint, tests and both image builds.
- Persian documentation: README plus architecture, search, API, data,
  security and operations guides.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GnFo6fNaHCTAkJbfcdkqtG

backend/tests/conftest.py

@@ -0,0 +1,120 @@
+"""Shared pytest fixtures."""
+
+from __future__ import annotations
+
+import pytest
+from rest_framework.test import APIClient
+
+from apps.accounts.models import Role, User
+from apps.profiles.models import Company, Profile, ProfileSkill, Skill
+
+PASSWORD = "Str0ng-Passw0rd!"  # noqa: S105 - test credential only
+
+
+@pytest.fixture
+def api_client() -> APIClient:
+    return APIClient()
+
+
+@pytest.fixture
+def make_user(db):  # noqa: ANN001, ANN201
+    def _make(email: str = "user@example.com", role: str = Role.VIEWER, **extra) -> User:
+        return User.objects.create_user(email=email, password=PASSWORD, role=role, **extra)
+
+    return _make
+
+
+@pytest.fixture
+def viewer(make_user) -> User:  # noqa: ANN001
+    return make_user("viewer@example.com", Role.VIEWER)
+
+
+@pytest.fixture
+def analyst(make_user) -> User:  # noqa: ANN001
+    return make_user("analyst@example.com", Role.ANALYST)
+
+
+@pytest.fixture
+def admin_user(make_user) -> User:  # noqa: ANN001
+    return make_user("admin@example.com", Role.ADMIN, is_staff=True, is_superuser=True)
+
+
+@pytest.fixture
+def auth_client(api_client):  # noqa: ANN001, ANN201
+    def _login(user: User) -> APIClient:
+        api_client.force_authenticate(user=user)
+        return api_client
+
+    return _login
+
+
+@pytest.fixture
+def sample_profiles(db) -> list[Profile]:  # noqa: ANN001
+    """Three profiles with enough variety to exercise every filter."""
+    from apps.profiles.importers import ProfileImporter
+
+    acme = Company.objects.create(name="acme corp", industry="software", size="51-200")
+    globex = Company.objects.create(name="globex", industry="banking", size="1001-5000")
+
+    people = [
+        {
+            "full_name": "sara python",
+            "job_title": "senior backend engineer",
+            "job_title_role": "engineering",
+            "seniority_levels": ["senior"],
+            "current_company": acme,
+            "industry": "software",
+            "location_country": "germany",
+            "location_name": "berlin, germany",
+            "years_experience": 9,
+            "summary": "Builds distributed systems with django and postgres.",
+            "skills": ["python", "django", "postgresql"],
+        },
+        {
+            "full_name": "john recruiter",
+            "job_title": "recruiting manager",
+            "job_title_role": "human_resources",
+            "seniority_levels": ["manager"],
+            "current_company": globex,
+            "industry": "banking",
+            "location_country": "united states",
+            "location_name": "denton, texas, united states",
+            "years_experience": 12,
+            "summary": "Talent acquisition and employer branding.",
+            "skills": ["recruiting", "hiring", "leadership"],
+        },
+        {
+            "full_name": "maria frontend",
+            "job_title": "frontend developer",
+            "job_title_role": "engineering",
+            "seniority_levels": [],
+            "current_company": acme,
+            "industry": "software",
+            "location_country": "spain",
+            "location_name": "madrid, spain",
+            "years_experience": 3,
+            "summary": "React and typescript specialist.",
+            "skills": ["react", "typescript", "javascript"],
+        },
+    ]
+
+    created: list[Profile] = []
+    for index, payload in enumerate(people, start=1):
+        skills = payload.pop("skills")
+        profile = Profile.objects.create(
+            external_id=str(1000 + index),
+            linkedin_url=f"linkedin.com/in/person-{index}",
+            skills_text=" ".join(skills),
+            companies_text=payload["current_company"].name,
+            **payload,
+        )
+        for position, name in enumerate(skills):
+            skill, _ = Skill.objects.get_or_create(
+                slug=Skill.make_slug(name), defaults={"name": name}
+            )
+            ProfileSkill.objects.create(profile=profile, skill=skill, position=position)
+        created.append(profile)
+
+    ProfileImporter._refresh_skill_counters()
+    ProfileImporter._refresh_search_vectors()
+    return created

backend/tests/test_auth_api.py

@@ -0,0 +1,113 @@
+"""Authentication, authorisation and PII masking at the API boundary."""
+
+from __future__ import annotations
+
+import pytest
+from django.urls import reverse
+
+from apps.accounts.models import Role, User
+from tests.conftest import PASSWORD
+
+pytestmark = pytest.mark.django_db
+
+
+def test_register_creates_a_viewer(api_client) -> None:  # noqa: ANN001
+    response = api_client.post(
+        reverse("v1:accounts:register"),
+        {
+            "email": "New.User@Example.com",
+            "full_name": "New User",
+            "password": PASSWORD,
+            "password_confirm": PASSWORD,
+        },
+        format="json",
+    )
+    assert response.status_code == 201
+    assert response.data["role"] == Role.VIEWER
+    # E-mails are normalised so "A@x.com" and "a@x.com" cannot both exist.
+    assert User.objects.get(email="new.user@example.com")
+
+
+def test_register_rejects_mismatched_and_weak_passwords(api_client) -> None:  # noqa: ANN001
+    url = reverse("v1:accounts:register")
+    mismatch = api_client.post(
+        url,
+        {"email": "a@example.com", "password": PASSWORD, "password_confirm": "other"},
+        format="json",
+    )
+    assert mismatch.status_code == 400
+    assert mismatch.data["error"]["code"] == "validation_error"
+
+    weak = api_client.post(
+        url,
+        {"email": "b@example.com", "password": "12345678", "password_confirm": "12345678"},
+        format="json",
+    )
+    assert weak.status_code == 400
+
+
+def test_login_returns_tokens_and_identity(api_client, viewer) -> None:  # noqa: ANN001
+    response = api_client.post(
+        reverse("v1:accounts:login"),
+        {"email": viewer.email, "password": PASSWORD},
+        format="json",
+    )
+    assert response.status_code == 200
+    assert {"access", "refresh", "user"} <= set(response.data)
+    assert response.data["user"]["role"] == Role.VIEWER
+
+
+def test_search_requires_authentication(api_client) -> None:  # noqa: ANN001
+    response = api_client.get(reverse("v1:search:search"))
+    assert response.status_code == 401
+    assert response.data["error"]["code"] in {"authentication_failed", "not_authenticated"}
+
+
+def test_reindex_is_admin_only(
+    auth_client, viewer, admin_user, monkeypatch
+) -> None:  # noqa: ANN001
+    url = reverse("v1:search:reindex")
+    assert auth_client(viewer).post(url).status_code == 403
+
+    monkeypatch.setattr(
+        "apps.search.indexing.rebuild_index", lambda *_args, **_kwargs: {"indexed": 0}
+    )
+    response = auth_client(admin_user).post(url)
+    assert response.status_code in {202, 503}
+
+
+@pytest.mark.parametrize(
+    ("role", "should_be_masked"),
+    [(Role.VIEWER, True), (Role.ANALYST, False), (Role.ADMIN, False)],
+)
+def test_contact_details_are_masked_for_unprivileged_roles(
+    auth_client, make_user, sample_profiles, role: str, should_be_masked: bool
+) -> None:  # noqa: ANN001
+    profile = sample_profiles[0]
+    profile.emails = [{"address": "sara.python@acme.com", "type": "professional"}]
+    profile.phone_numbers = ["+19402058928"]
+    profile.save(update_fields=["emails", "phone_numbers"])
+
+    user = make_user(f"{role}@example.com", role)
+    response = auth_client(user).get(reverse("v1:profiles:detail", args=[profile.id]))
+
+    assert response.status_code == 200
+    assert response.data["pii_masked"] is should_be_masked
+    address = response.data["emails"][0]["address"]
+    assert (address != "sara.python@acme.com") is should_be_masked
+
+
+def test_response_carries_a_request_id_header(api_client) -> None:  # noqa: ANN001
+    response = api_client.get(reverse("v1:core:liveness"))
+    assert response.status_code == 200
+    assert response["X-Request-ID"]
+
+
+def test_client_supplied_request_id_is_echoed(api_client) -> None:  # noqa: ANN001
+    response = api_client.get(reverse("v1:core:liveness"), HTTP_X_REQUEST_ID="abc-123")
+    assert response["X-Request-ID"] == "abc-123"
+
+
+def test_malicious_request_id_is_replaced(api_client) -> None:  # noqa: ANN001
+    response = api_client.get(reverse("v1:core:liveness"), HTTP_X_REQUEST_ID="<script>x</script>")
+    assert "<script>" not in response["X-Request-ID"]

backend/tests/test_dataset_repair.py

@@ -0,0 +1,123 @@
+"""
+Tests for the self-healing CSV reader.
+
+Each test reproduces one defect that is actually present in the supplied export
+so a regression in the repair logic fails loudly instead of quietly importing
+garbage.
+"""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import Path
+
+import pytest
+
+from apps.profiles.dataset import DatasetReader
+
+HEADER = (
+    "full_name,first_name,last_name,gender,linkedin_url,linkedin_username,linkedin_id,"
+    "industry,job_title,job_title_role,job_title_levels,job_company_name,location_name,"
+    "location_country,skills,experience,summary"
+)
+
+
+def _write(tmp_path: Path, body: str) -> Path:
+    path = tmp_path / "sample.csv"
+    path.write_text(textwrap.dedent(body).lstrip(), encoding="utf-8")
+    return path
+
+
+@pytest.fixture
+def read(tmp_path):  # noqa: ANN001, ANN201
+    def _read(body: str):  # noqa: ANN202
+        return DatasetReader(_write(tmp_path, body)).read()
+
+    return _read
+
+
+def test_clean_row_is_read_verbatim(read) -> None:  # noqa: ANN001
+    records, report = read(
+        f"""
+        {HEADER}
+        jane doe,jane,doe,female,linkedin.com/in/janedoe,janedoe,123456,software,backend engineer,engineering,"['senior']",acme,"berlin, germany",germany,"['python', 'django']","[{{'company': {{'name': 'acme'}}, 'title': {{'name': 'backend engineer'}}}}]",Loves databases.
+        """
+    )
+    assert report.records == 1
+    record = records[0]
+    assert record["full_name"] == "jane doe"
+    assert record["job_title_role"] == "engineering"
+    assert record["skills"] == "['python', 'django']"
+
+
+def test_leading_watermark_column_is_stripped(read) -> None:  # noqa: ANN001
+    records, _ = read(
+        f"""
+        {HEADER}
+        H:\\New folder\\leak\\linkedin\\@BreachedData1,jane doe,jane,doe,female,linkedin.com/in/janedoe,janedoe,123456,software,backend engineer,engineering,"['senior']",acme,"berlin, germany",germany,"['python']","[]",Hi.
+        """
+    )
+    assert records[0]["full_name"] == "jane doe"
+    assert records[0]["linkedin_url"] == "linkedin.com/in/janedoe"
+
+
+def test_missing_column_does_not_shift_the_rest_of_the_row(read) -> None:  # noqa: ANN001
+    """``job_title_role`` is absent - every later value must still land right."""
+    records, _ = read(
+        f"""
+        {HEADER}
+        jane doe,jane,doe,female,linkedin.com/in/janedoe,janedoe,123456,software,backend engineer,"['senior']",acme,"berlin, germany",germany,"['python']","[]",Hi.
+        """
+    )
+    record = records[0]
+    assert record["job_title_role"] == ""
+    assert record["job_title_levels"] == "['senior']"
+    assert record["job_company_name"] == "acme"
+    assert record["location_country"] == "germany"
+    assert record["skills"] == "['python']"
+
+
+def test_values_that_fail_their_signature_are_discarded(read) -> None:  # noqa: ANN001
+    """A non-URL in the URL column is dropped rather than persisted."""
+    records, report = read(
+        f"""
+        {HEADER}
+        jane doe,jane,doe,female,not-a-linkedin-url,janedoe,123456,software,engineer,engineering,"['senior']",acme,"berlin, germany",germany,"['python']","[]",Hi.
+        """
+    )
+    assert records[0]["linkedin_url"] == ""
+    assert report.discarded_values >= 1
+
+
+def test_repeated_header_and_duplicate_person_are_removed(read) -> None:  # noqa: ANN001
+    row = (
+        "jane doe,jane,doe,female,linkedin.com/in/janedoe,janedoe,123456,software,engineer,"
+        'engineering,"[\'senior\']",acme,"berlin, germany",germany,"[\'python\']","[]",Hi.'
+    )
+    records, report = read(f"{HEADER}\n{row}\n{HEADER}\n{row}\n")
+    assert report.duplicate_headers == 1
+    assert report.duplicate_records == 1
+    assert len(records) == 1
+
+
+def test_row_split_by_a_stray_quote_is_reassembled(read) -> None:  # noqa: ANN001
+    """A record cut in half by broken quoting is stitched back together."""
+    records, report = read(
+        f"""
+        {HEADER}
+        jane doe,jane,doe,female,linkedin.com/in/janedoe,janedoe,123456,software,engineer
+        engineering,"['senior']",acme,"berlin, germany",germany,"['python', 'sql']","[]",Hi.
+        """
+    )
+    assert len(records) == 1
+    assert report.repaired_rows >= 1
+    assert records[0]["skills"] == "['python', 'sql']"
+    assert records[0]["location_country"] == "germany"
+
+
+def test_empty_file_yields_no_records(tmp_path) -> None:  # noqa: ANN001
+    path = tmp_path / "empty.csv"
+    path.write_text("", encoding="utf-8")
+    records, report = DatasetReader(path).read()
+    assert records == []
+    assert report.records == 0

backend/tests/test_importer.py

@@ -0,0 +1,128 @@
+"""The importer must normalise, enrich and stay idempotent."""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import Path
+
+import pytest
+
+from apps.profiles.importers import ProfileImporter
+from apps.profiles.models import Company, Education, Experience, Profile, Skill
+
+pytestmark = pytest.mark.django_db
+
+HEADER = (
+    "full_name,first_name,last_name,gender,linkedin_url,linkedin_username,linkedin_id,"
+    "industry,job_title,job_title_role,job_title_levels,job_company_name,job_company_size,"
+    "location_name,location_country,inferred_years_experience,linkedin_connections,"
+    "skills,experience,education,emails,phone_numbers,summary"
+)
+
+EXPERIENCE = (
+    "[{'company': {'name': 'acme corp', 'size': '51-200', 'industry': 'software', "
+    "'location': {'name': 'berlin, germany', 'country': 'germany'}}, "
+    "'title': {'name': 'backend engineer', 'role': 'engineering', 'sub_role': 'backend', "
+    "'levels': ['senior']}, 'start_date': '2019-04', 'end_date': None, 'is_primary': True}]"
+)
+EDUCATION = (
+    "[{'school': {'name': 'tu berlin', 'type': 'post-secondary institution', "
+    "'location': {'name': 'berlin, germany', 'country': 'germany'}}, "
+    "'degrees': ['bachelors'], 'majors': ['computer science'], 'minors': [], "
+    "'start_date': '2012', 'end_date': '2016', 'gpa': None}]"
+)
+
+
+def _dataset(tmp_path: Path, row: str) -> str:
+    path = tmp_path / "dataset.csv"
+    path.write_text(f"{HEADER}\n{row}\n", encoding="utf-8")
+    return str(path)
+
+
+def _row(*, with_top_level_role: bool = True) -> str:
+    role = "engineering," if with_top_level_role else ""
+    return (
+        f"jane doe,jane,doe,female,linkedin.com/in/janedoe,janedoe,55501,software,"
+        f'backend engineer,{role}"[\'senior\']",acme corp,51-200,"berlin, germany",germany,'
+        f"8.0,540.0,\"['Python', 'django', 'python']\",\"{EXPERIENCE}\",\"{EDUCATION}\","
+        f"\"[{{'address': 'jane@acme.com', 'type': 'professional'}}]\",\"['+491701234567']\","
+        f"Backend engineer."
+    )
+
+
+def test_import_populates_the_relational_model(tmp_path) -> None:  # noqa: ANN001
+    stats = ProfileImporter(_dataset(tmp_path, _row())).run()
+
+    assert stats.created == 1
+    profile = Profile.objects.get()
+    assert profile.full_name == "jane doe"
+    assert profile.years_experience == 8
+    assert profile.connections == 540
+    assert profile.current_company.name == "acme corp"
+    assert Experience.objects.filter(profile=profile).count() == 1
+    assert Education.objects.get(profile=profile).majors == ["computer science"]
+    assert profile.emails == [{"address": "jane@acme.com", "type": "professional"}]
+
+
+def test_skills_are_deduplicated_and_normalised(tmp_path) -> None:  # noqa: ANN001
+    ProfileImporter(_dataset(tmp_path, _row())).run()
+    profile = Profile.objects.get()
+    names = [link.skill.name for link in profile.profile_skills.all()]
+    # "Python" and "python" collapse into a single normalised skill.
+    assert names == ["python", "django"]
+    assert Skill.objects.get(slug="python").profile_count == 1
+
+
+def test_missing_top_level_fields_are_derived_from_the_experience_blob(
+    tmp_path,
+) -> None:  # noqa: ANN001
+    """The export frequently omits ``job_title_role``; the nested data has it."""
+    ProfileImporter(_dataset(tmp_path, _row(with_top_level_role=False))).run()
+    profile = Profile.objects.get()
+    assert profile.job_title_role == "engineering"
+    assert profile.job_title_sub_role == "backend"
+    assert profile.current_company.name == "acme corp"
+
+
+def test_import_is_idempotent(tmp_path) -> None:  # noqa: ANN001
+    path = _dataset(tmp_path, _row())
+    first = ProfileImporter(path).run()
+    second = ProfileImporter(path).run()
+
+    assert first.created == 1
+    assert second.created == 0
+    assert second.updated == 1
+    assert Profile.objects.count() == 1
+    assert Company.objects.filter(name="acme corp").count() == 1
+    # Child rows are replaced, never duplicated.
+    assert Experience.objects.count() == 1
+
+
+def test_search_vector_is_populated(tmp_path) -> None:  # noqa: ANN001
+    ProfileImporter(_dataset(tmp_path, _row())).run()
+    profile = Profile.objects.get()
+    assert profile.search_vector is not None
+    assert "django" in profile.skills_text
+
+
+def test_management_command_runs(tmp_path, capsys) -> None:  # noqa: ANN001
+    from django.core.management import call_command
+
+    call_command("import_profiles", "--path", _dataset(tmp_path, _row()), "--truncate")
+    assert Profile.objects.count() == 1
+    assert "profiles_created" in capsys.readouterr().out
+
+
+def test_broken_dataset_reports_but_does_not_crash(tmp_path) -> None:  # noqa: ANN001
+    path = tmp_path / "broken.csv"
+    path.write_text(
+        textwrap.dedent(
+            f"""
+            {HEADER}
+            ,,,,,,,,,,,,,,,,,,,,,,
+            """
+        ).lstrip(),
+        encoding="utf-8",
+    )
+    stats = ProfileImporter(str(path)).run()
+    assert stats.report.records >= 0

backend/tests/test_indexing.py

@@ -0,0 +1,40 @@
+"""The index document must stay in sync with the mapping - and hide PII."""
+
+from __future__ import annotations
+
+import pytest
+
+from apps.search.indexing import INDEX_MAPPINGS, build_document
+
+pytestmark = pytest.mark.django_db
+
+
+def test_document_only_contains_mapped_fields(sample_profiles) -> None:  # noqa: ANN001
+    """
+    The mapping is ``dynamic: strict``: an unmapped field makes Elasticsearch
+    reject the whole document, so this assertion protects every reindex.
+    """
+    document = build_document(sample_profiles[0])
+    assert set(document) <= set(INDEX_MAPPINGS["properties"])
+
+
+def test_document_never_carries_contact_details(sample_profiles) -> None:  # noqa: ANN001
+    profile = sample_profiles[0]
+    profile.emails = [{"address": "sara@acme.com", "type": "professional"}]
+    profile.phone_numbers = ["+491701234567"]
+    profile.save(update_fields=["emails", "phone_numbers"])
+
+    document = build_document(profile)
+    serialised = str(document)
+    assert "emails" not in document
+    assert "phone_numbers" not in document
+    assert "sara@acme.com" not in serialised
+    assert "+491701234567" not in serialised
+
+
+def test_document_denormalises_the_related_rows(sample_profiles) -> None:  # noqa: ANN001
+    document = build_document(sample_profiles[0])
+    assert document["full_name"] == "sara python"
+    assert document["company"] == "acme corp"
+    assert "python" in document["skills"]
+    assert document["years_experience"] == 9

backend/tests/test_privacy.py

@@ -0,0 +1,47 @@
+"""Masking helpers must never leak the original value."""
+
+from __future__ import annotations
+
+import pytest
+
+from apps.profiles.privacy import mask_email, mask_emails, mask_phone, mask_phones
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        ("joseph.holland@garverusa.com", "jo************@garverusa.com"),
+        # A single character local part is hidden completely - keeping it would
+        # reveal the whole address.
+        ("a@b.com", "*@b.com"),
+    ],
+)
+def test_mask_email_keeps_domain_and_hides_local_part(raw: str, expected: str) -> None:
+    masked = mask_email(raw)
+    assert masked == expected
+    assert masked.endswith("@" + raw.split("@")[1])
+
+
+def test_mask_email_handles_garbage() -> None:
+    assert mask_email("not-an-email") == "***"
+    assert mask_email("") == "***"
+
+
+def test_mask_phone_hides_the_middle() -> None:
+    masked = mask_phone("+19402058928")
+    assert masked.startswith("+1940")
+    assert masked.endswith("28")
+    assert "*" in masked
+    assert "20589" not in masked
+
+
+def test_mask_phone_rejects_short_input() -> None:
+    assert mask_phone("+123") == "***"
+
+
+def test_list_helpers_preserve_structure() -> None:
+    emails = [{"address": "a.person@corp.com", "type": "professional"}]
+    masked = mask_emails(emails)
+    assert masked[0]["type"] == "professional"
+    assert masked[0]["address"] != emails[0]["address"]
+    assert mask_phones(["+19402058928"])[0] != "+19402058928"

backend/tests/test_query_builder.py

@@ -0,0 +1,76 @@
+"""
+Unit tests for the Elasticsearch query builder.
+
+``build_query`` is a pure function, so the ranking and filtering rules can be
+asserted without a running cluster - the fastest possible feedback loop for the
+part of the system that is easiest to get subtly wrong.
+"""
+
+from __future__ import annotations
+
+from apps.search.backends.elastic import build_query
+from apps.search.types import SORT_EXPERIENCE_DESC, SORT_NAME, SearchRequest
+
+
+def _bool(request: SearchRequest) -> dict:
+    return build_query(request)["query"]["bool"]
+
+
+def test_empty_query_matches_everything() -> None:
+    clause = _bool(SearchRequest())
+    assert clause["must"] == [{"match_all": {}}]
+    assert clause["filter"] == []
+
+
+def test_keyword_query_uses_fuzzy_multi_match_and_phrase_boost() -> None:
+    clause = _bool(SearchRequest(q="python developer"))
+    multi_match = clause["must"][0]["multi_match"]
+    assert multi_match["query"] == "python developer"
+    assert multi_match["fuzziness"] == "AUTO"
+    assert any(field.startswith("full_name^") for field in multi_match["fields"])
+    # The phrase clause only boosts; it must never be required.
+    assert clause["should"][0]["multi_match"]["type"] == "phrase"
+
+
+def test_filters_are_terms_clauses_in_filter_context() -> None:
+    clause = _bool(
+        SearchRequest(skills=("python", "django"), countries=("germany",), seniority=("senior",))
+    )
+    assert {"terms": {"skills.keyword": ["python", "django"]}} in clause["filter"]
+    assert {"terms": {"location_country": ["germany"]}} in clause["filter"]
+    assert {"terms": {"seniority_levels": ["senior"]}} in clause["filter"]
+    # Filters must not leak into the scoring clauses.
+    assert clause["must"] == [{"match_all": {}}]
+
+
+def test_experience_range_is_translated_to_a_range_filter() -> None:
+    clause = _bool(SearchRequest(min_experience=5, max_experience=10))
+    assert {"range": {"years_experience": {"gte": 5, "lte": 10}}} in clause["filter"]
+
+    open_ended = _bool(SearchRequest(min_experience=5))
+    assert {"range": {"years_experience": {"gte": 5}}} in open_ended["filter"]
+
+
+def test_pagination_maps_to_from_and_size() -> None:
+    body = build_query(SearchRequest(page=3, page_size=25))
+    assert body["from"] == 50
+    assert body["size"] == 25
+    assert body["track_total_hits"] is True
+
+
+def test_sort_options() -> None:
+    assert build_query(SearchRequest(sort=SORT_NAME))["sort"][0] == {"full_name.keyword": "asc"}
+    assert build_query(SearchRequest(sort=SORT_EXPERIENCE_DESC))["sort"][0] == {
+        "years_experience": {"order": "desc", "missing": "_last"}
+    }
+    assert build_query(SearchRequest())["sort"][0] == "_score"
+
+
+def test_highlight_only_requested_with_a_keyword() -> None:
+    assert "highlight" not in build_query(SearchRequest())
+    assert "highlight" in build_query(SearchRequest(q="python"))
+
+
+def test_facets_can_be_switched_off() -> None:
+    assert "aggs" in build_query(SearchRequest())
+    assert "aggs" not in build_query(SearchRequest(include_facets=False))

backend/tests/test_search_api.py

@@ -0,0 +1,145 @@
+"""
+End-to-end tests of the search endpoint against the PostgreSQL backend.
+
+They pin down the behaviour the task description asks for: keyword search plus
+at least two filters, and a correct contract between frontend and backend.
+"""
+
+from __future__ import annotations
+
+import pytest
+from django.urls import reverse
+
+pytestmark = pytest.mark.django_db
+
+
+def search(client, **params):  # noqa: ANN001, ANN201
+    return client.get(reverse("v1:search:search"), params)
+
+
+def names(response) -> list[str]:  # noqa: ANN001
+    return [hit["full_name"] for hit in response.data["results"]]
+
+
+def test_empty_query_returns_every_profile(
+    auth_client, analyst, sample_profiles
+) -> None:  # noqa: ANN001
+    response = search(auth_client(analyst))
+    assert response.status_code == 200
+    assert response.data["count"] == len(sample_profiles)
+    assert response.data["backend"] == "postgres"
+
+
+def test_keyword_matches_skills_and_summary(
+    auth_client, analyst, sample_profiles
+) -> None:  # noqa: ANN001
+    response = search(auth_client(analyst), q="django")
+    assert names(response) == ["sara python"]
+
+
+def test_keyword_matches_a_person_name(
+    auth_client, analyst, sample_profiles
+) -> None:  # noqa: ANN001
+    assert names(search(auth_client(analyst), q="maria")) == ["maria frontend"]
+
+
+def test_keyword_tolerates_a_typo_in_the_name(
+    auth_client, analyst, sample_profiles
+) -> None:  # noqa: ANN001
+    """Trigram similarity is what makes ``jhon`` still find ``john``."""
+    assert "john recruiter" in names(search(auth_client(analyst), q="jhon recruiter"))
+
+
+def test_skill_filter(auth_client, analyst, sample_profiles) -> None:  # noqa: ANN001
+    assert names(search(auth_client(analyst), skills="react")) == ["maria frontend"]
+
+
+def test_multiple_values_inside_one_filter_are_or_combined(
+    auth_client, analyst, sample_profiles
+) -> None:  # noqa: ANN001
+    response = search(auth_client(analyst), skills="react,django")
+    assert sorted(names(response)) == ["maria frontend", "sara python"]
+
+
+def test_different_filters_are_and_combined(
+    auth_client, analyst, sample_profiles
+) -> None:  # noqa: ANN001
+    response = search(auth_client(analyst), skills="react,django", countries="spain")
+    assert names(response) == ["maria frontend"]
+
+
+def test_role_and_experience_filters(auth_client, analyst, sample_profiles) -> None:  # noqa: ANN001
+    response = search(auth_client(analyst), roles="engineering", min_experience=5)
+    assert names(response) == ["sara python"]
+
+
+def test_repeated_query_parameters_are_supported(
+    auth_client, analyst, sample_profiles
+) -> None:  # noqa: ANN001
+    client = auth_client(analyst)
+    response = client.get(f"{reverse('v1:search:search')}?skills=react&skills=django")
+    assert sorted(names(response)) == ["maria frontend", "sara python"]
+
+
+def test_facets_reflect_the_filtered_result_set(
+    auth_client, analyst, sample_profiles
+) -> None:  # noqa: ANN001
+    response = search(auth_client(analyst), roles="engineering")
+    countries = {bucket["key"] for bucket in response.data["facets"]["country"]}
+    assert countries == {"germany", "spain"}
+    assert response.data["facets"]["skills"]
+
+
+def test_sorting_by_experience(auth_client, analyst, sample_profiles) -> None:  # noqa: ANN001
+    assert names(search(auth_client(analyst), sort="-experience"))[0] == "john recruiter"
+    assert names(search(auth_client(analyst), sort="experience"))[0] == "maria frontend"
+    assert names(search(auth_client(analyst), sort="name"))[0] == "john recruiter"
+
+
+def test_pagination_metadata(auth_client, analyst, sample_profiles) -> None:  # noqa: ANN001
+    response = search(auth_client(analyst), page_size=2, page=2, sort="name")
+    assert response.data["page"] == 2
+    assert response.data["page_size"] == 2
+    assert response.data["total_pages"] == 2
+    assert len(response.data["results"]) == 1
+
+
+def test_highlight_is_returned_for_keyword_searches(
+    auth_client, analyst, sample_profiles
+) -> None:  # noqa: ANN001
+    hit = search(auth_client(analyst), q="django").data["results"][0]
+    assert "<mark>" in " ".join(hit["highlight"].get("skills", []))
+
+
+def test_invalid_experience_range_is_rejected(auth_client, analyst) -> None:  # noqa: ANN001
+    response = search(auth_client(analyst), min_experience=10, max_experience=2)
+    assert response.status_code == 400
+    assert response.data["error"]["code"] == "validation_error"
+
+
+def test_page_size_is_capped(auth_client, analyst) -> None:  # noqa: ANN001
+    assert search(auth_client(analyst), page_size=5000).status_code == 400
+
+
+def test_deep_pagination_is_refused(auth_client, analyst) -> None:  # noqa: ANN001
+    assert search(auth_client(analyst), page=99999, page_size=100).status_code == 400
+
+
+def test_unknown_filter_values_return_an_empty_page_not_an_error(
+    auth_client, analyst, sample_profiles
+) -> None:  # noqa: ANN001
+    response = search(auth_client(analyst), skills="cobol")
+    assert response.status_code == 200
+    assert response.data["count"] == 0
+
+
+def test_suggest_endpoint(auth_client, analyst, sample_profiles) -> None:  # noqa: ANN001
+    response = auth_client(analyst).get(reverse("v1:search:suggest"), {"q": "mar"})
+    assert response.status_code == 200
+    assert "maria frontend" in response.data["suggestions"]
+
+
+def test_skill_dictionary_endpoint(auth_client, analyst, sample_profiles) -> None:  # noqa: ANN001
+    response = auth_client(analyst).get(reverse("v1:profiles:skills"), {"q": "py"})
+    assert response.status_code == 200
+    assert any(item["name"] == "python" for item in response.data)