feat(backend): initialize project structure

backend/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "visual-graph"
+version = "0.1.0"
+description = "Graph-based visual search and scene exploration using computer vision and Neo4j."
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.30",
+    "pydantic-settings>=2.4",
+]
+
+[project.scripts]
+visual-graph = "visual_graph.__main__:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "hypothesis>=6.100",
+    "httpx>=0.27",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/visual_graph"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers -m 'not integration and not inference'"
+markers = [
+    "integration: requires a running Neo4j instance",
+    "inference: runs the real detector (slow, needs local weights)",
+]
+
+[tool.ruff]
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+files = ["src"]
+strict = true

backend/src/visual_graph/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("visual-graph")

backend/src/visual_graph/__main__.py

@@ -0,0 +1,18 @@
+import uvicorn
+
+from visual_graph.config import get_settings
+
+
+def main() -> None:
+    settings = get_settings()
+    uvicorn.run(
+        "visual_graph.main:create_app",
+        factory=True,
+        host=settings.api_host,
+        port=settings.api_port,
+        reload=settings.api_reload,
+    )
+
+
+if __name__ == "__main__":
+    main()

backend/src/visual_graph/api/health.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health/live")
+def live() -> dict[str, str]:
+    return {"status": "ok"}

backend/src/visual_graph/config.py

@@ -0,0 +1,17 @@
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    app_name: str = "VisualGraph"
+    api_host: str = "127.0.0.1"
+    api_port: int = 8000
+    api_reload: bool = False
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

backend/src/visual_graph/main.py

@@ -0,0 +1,12 @@
+from fastapi import FastAPI
+
+from visual_graph import __version__
+from visual_graph.api import health
+from visual_graph.config import get_settings
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+    app = FastAPI(title=settings.app_name, version=__version__)
+    app.include_router(health.router)
+    return app

backend/tests/api/test_health.py

@@ -0,0 +1,8 @@
+from fastapi.testclient import TestClient
+
+
+def test_live(client: TestClient) -> None:
+    response = client.get("/health/live")
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}

backend/tests/conftest.py

@@ -0,0 +1,9 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from visual_graph.main import create_app
+
+
+@pytest.fixture
+def client() -> TestClient:
+    return TestClient(create_app())

backend/tests/unit/test_package.py

@@ -0,0 +1,5 @@
+import visual_graph
+
+
+def test_package_exposes_version() -> None:
+    assert visual_graph.__version__