:PROPERTIES:
:ID: d09e7464-e494-433b-beb8-e0742e904c93
:END:

#+title: big-jar-of-pickles/infra
#+filetags: :project: :knowledge: :infra:

* big-jar-of-pickles/infra
Detailed reasoning behind the two-repo infra split for [[big-jar-of-pickles]].

** Architecture
- Two-repo split: [[homey]] (/home/aner/projects/selfhosted/homey) hosts shared self-hosted infra — Postgres+pgvector, Redis, self-hosted Langfuse (all enabled/load-bearing) — plus a built-but-disabled Aegra module (services.aegra.enable = false). big-jar-of-pickles itself is purely the graph-running application.
- Rejected LangGraph's own self-hosted "Server" (langgraph-api): Elastic License 2.0, needs a paid enterprise key in production; only `langgraph dev` (in-memory, non-persistent) is free. Conflicts with the project's FOSS ethos (README already chose Langfuse over LangSmith for the same reason).
- Evaluated Aegra (github.com/ibbybuilds/aegra) as a FOSS (Apache 2.0, ~1.2k stars, active) reimplementation of that running layer — FastAPI+Postgres+Redis+OTLP, graphs registered via aegra.json (`{"graphs": {"id": "path/to/file.py:var"}}`). Confirmed this config is read only at process startup via filesystem paths, NOT dynamically hot-reloadable — the expected "persistent platform, swap graphs live" benefit doesn't actually hold. Decision: build it into homey but leave disabled; plain library use is simpler for an experimentation-focused project.
- This repo's actual approach: `langgraph` library directly (MIT) + a Postgres checkpointer (`langgraph.checkpoint.postgres`) against homey's shared Postgres for cross-run persistence, direct `langfuse` Python SDK v3 tracing (`from langfuse.langchain import CallbackHandler`, reads LANGFUSE_PUBLIC_KEY/SECRET_KEY/HOST from env automatically), Guardrails AI core `Validator`/`register_validator` API (not Guardrails Hub — Hub validators need a separate `guardrails configure`/`hub install` step that isn't nix-hermetic), and an LLM-as-judge node.
- Packaging: uv2nix (pyproject-nix + build-system-pkgs) built cleanly on the first `nix build` attempt for this dependency set (langgraph, langgraph-checkpoint-postgres, psycopg[binary], langfuse, guardrails-ai, openai) — no build-system overrides needed. flake.nix pins nixpkgs to nixos-25.05 to match homey. Confirmed working: `nix build .#default`, `nix develop`, `nix flake show`.
- homey integration pattern (confirmed by reading the eurovote flake + homey repo): an app flake exposes `nixosModules.default` -> homey adds it as a flake input -> wraps it in `modules/services/<app>.nix` (adds a `homey.<app>.enable` option, sops secrets, Caddy vhost, Authelia rule, uptime-kuma monitor, backup path) -> the host (`hosts/pi-main/default.nix`) flips the enable flag. homey pins nixpkgs-25.05 (not unstable); pi-main is a real Raspberry Pi 4 (resource-constrained — zram swap sized for ~8GB RAM).

** Gotchas
- The homey-side feature module (Postgres+pgvector, Redis, Langfuse oci-containers, dormant Aegra module) has NOT been implemented yet as of 2026-09-11 — only planned/researched. Separate work still to do in the homey repo.
- big-jar-of-pickles' nixosModules.default is not yet wired into homey / enabled on pi-main.

** Key Files
- /home/aner/projects/selfhosted/homey/modules/services/eurovote.nix — reference pattern to replicate for wiring big-jar-of-pickles (and any future homey infra module) into homey
- /home/aner/projects/apps/eurovote/flake.nix — reference nixosModule shape (options, sops ExecStartPre, systemd service)

** Related
[[big-jar-of-pickles]]

[[id:dc2ddfad-ada9-4f0d-ae35-806e8a1a2def][homey/big-jar-of-pickles]]