02 — Repository evidence and reuse plan
02 — Repository evidence and reuse plan#
Evidence ledger#
| Source | Observed | Consequence |
|---|---|---|
| Platform doors | Zotline is the network-layer offering at corporate egress | Preserve separation from Agent and SDK |
| Deployment onboarding | Zotline routes to a sales conversation | Build actual appliance onboarding |
| Go entry point | Policy bootstrap/cache, proxy and desktop bridge startup | Reuse engine lifecycle; introduce a gateway-specific supervisor |
| Go proxy | CONNECT, generated certificates and bypass tunneling | Add enterprise auth, destination ACL and scoped identity |
| Go configuration | Loopback defaults and desktop-related settings | Existing flags are not a hardened network-appliance configuration |
| Certificate authority | Local certificate machinery | Add customer intermediate lifecycle and fleet key isolation |
| Redaction engine | Multiple engine/runtime paths | Release must pin supported engine and artifact versions |
| Python detection | Separate Python implementation | Establish parity where promised with fixtures |
| API startup | API plus in-process background jobs and hardcoded CORS entries | Externalize configuration and separate worker scheduling |
| Database layer | SQLite/PostgreSQL adaptation; production requires PostgreSQL | Supported production appliance uses PostgreSQL |
| Agent identity | Per-device credentials bound to enrolling user | Gateway identity must not represent all traffic as installer identity |
| Kinde auth | Hosted identity coupling | Add portable IdP integration across login and lifecycle operations |
| Desktop router | Enrollment, updates and contextual redaction service | Extract reusable services; avoid gateway masquerading as desktop |
| Team evaluator | Optional model-assisted rules, default-on toggle | Missing model must produce explicit capability/error state |
| File abstraction | Local disk/file-store operations | Use durable paths and verified customer object-store adapters |
| Audit worker | Declared single-worker assumption | Add leases and idempotency before HA |
| URL guard | Private SIEM destinations rejected | Replace with controlled customer allowlisting, not unrestricted bypass |
| ECR Compose | nginx/messenger sidecars; API/UI managed separately | Vendor production deployment is not customer installation automation |
| Database Terraform | Single-AZ and permissive deletion choices | New production templates need retention and resilience decisions |
| Main CI | Placeholder build job | Do not assume repository-level CI proves an appliance release |
Reuse boundaries#
Extract the Go parser/detector/rewriter and policy interfaces into a shared Go module, preserving import boundaries and tests. Both desktop builds and the gateway consume a pinned revision. Keep desktop process capture, OS certificates and window management outside that module.
Add a zotline-gateway entry point that owns server configuration, connection identity, health/readiness, fleet enrollment, durable spool and production limits. Do not expose the existing loopback proxy to a network simply by changing its bind address.
Keep the FastAPI application as a modular control plane initially. New gateway routers should call shared policy and audit services rather than copy desktop routers. Introduce identity/storage/inference/license interfaces so appliance mode does not import hosted-only behavior on startup.
The Next.js UI needs runtime deployment discovery or a consistently relative API origin. Configuration baked into NEXT_PUBLIC_* during build is unsuitable for arbitrary customer hostnames without a deliberate routing strategy. Serve same-origin management where possible and test auth callbacks/reverse-proxy headers.
Cross-cutting migration checklist#
- Inventory every outbound dependency: authentication, management APIs, model calls, notifications, email, update downloads, telemetry and catalog refresh.
- Make deployment mode explicit and validated. Refuse production startup with auth bypass or unresolved mandatory settings.
- Remove hardcoded vendor hostnames from functional flows in appliance mode. Preserve legacy API compatibility for existing hosted clients.
- Move migrations to a controlled job. Avoid competing startup migrations when adding replicas.
- Move scheduled jobs out of every web-worker lifespan. Each durable job must have one claimant or idempotent processing.
- Replace local temporary storage assumptions with durable, quota-controlled paths where persistence is required.
- Verify logging and diagnostics along every redaction path, including error branches.
- Add gateway-specific fleet and coverage UI; do not imply endpoint inventory from network observations.
Existing behavior that needs explicit decisions#
The Go engine has policy caching, but the proposed signed-bundle protocol and revocation rules must be implemented and tested. The API health endpoint confirms process response, not complete service readiness. The private SIEM development bypass is intentionally forbidden in production; a customer-safe configuration path is new work.
OPENAI_BASE_URL is a useful existing extension point. It does not prove compatibility with arbitrary local models, output schemas, token limits or error semantics. A model profile needs its own acceptance suite.
The desktop recorder includes evidence-building paths. Audit privacy must be checked at the actual serialization boundary; documentation saying “metadata” does not prove every string is free of customer content.
Exit from repository exploration#
Before implementation, create a dependency inventory and record exact source revision, Go/Python engine versions, supported test commands and CI results. This handbook intentionally avoids claiming tests were run or product coverage was certified during the documentation review.