tiny-forge/plans/observability-proxy-mgmt/phase-1-schema-eventlog.md

Phase 1: Schema, Models & Event Log Backend

Status: ⬜ Not Started Parent plan: PLAN.md Domain: backend

Objective

Lay the database foundation for all new features and implement the persistent event log system.

Tasks

• Task 1: Add event_log table to schema (id INTEGER PK AUTOINCREMENT, source TEXT, severity TEXT, message TEXT, metadata TEXT JSON, created_at TEXT)
• Task 2: Add standalone_proxies table to schema (id TEXT PK, domain TEXT UNIQUE, destination_url TEXT, destination_port INTEGER, ssl_certificate_id INTEGER, npm_proxy_id INTEGER, health_status TEXT, health_checked_at TEXT, created_at TEXT, updated_at TEXT)
• Task 3: Add stale_threshold_days column to settings table (migration, default 7)
• Task 4: Create internal/store/eventlog.go — store methods: InsertEvent, ListEvents (paginated, filterable by severity/source/date range), GetEventStats (counts by severity), PruneEvents (delete old entries)
• Task 5: Create internal/store/standalone_proxy.go — store methods: CreateStandaloneProxy, GetStandaloneProxy, ListStandaloneProxies, UpdateStandaloneProxy, DeleteStandaloneProxy, UpdateProxyHealth
• Task 6: Create Go models in internal/store/models.go — EventLog struct, StandaloneProxy struct
• Task 7: Update settings model to include stale_threshold_days field; update GetSettings/SaveSettings
• Task 8: Enhance event bus to auto-persist warn/error events — add a subscriber in events.Bus that writes to store
• Task 9: Add API endpoints: GET /api/events/log (paginated, filterable), GET /api/events/log/stats
• Task 10: Add new SSE event type event_log — broadcast persistent events in real-time
• Task 11: Add frontend types: EventLogEntry, StandaloneProxy interfaces in types.ts
• Task 12: Add API functions in api.ts: fetchEventLog, fetchEventLogStats

Files to Modify/Create

• internal/store/store.go — Add schema for event_log, standalone_proxies tables; migration for stale_threshold_days
• internal/store/models.go — Add EventLog, StandaloneProxy structs; update Settings struct
• internal/store/eventlog.go — NEW: Event log store methods
• internal/store/standalone_proxy.go — NEW: Standalone proxy store methods
• internal/store/settings.go — Update GetSettings/SaveSettings for new field
• internal/events/bus.go — Add persistent event subscriber
• internal/api/router.go — Mount new event log routes
• internal/api/eventlog.go — NEW: Event log HTTP handlers
• web/src/lib/types.ts — Add EventLogEntry, StandaloneProxy types
• web/src/lib/api.ts — Add fetchEventLog, fetchEventLogStats functions

Acceptance Criteria

• event_log and standalone_proxies tables created on startup (migration is idempotent)
• stale_threshold_days setting accessible via settings API
• Events with warn/error severity auto-persisted from event bus
• GET /api/events/log returns paginated, filterable results
• GET /api/events/log/stats returns severity counts
• Frontend types and API functions ready for downstream UI phases
• Existing functionality unchanged — all current tests/builds pass

Notes

• Follow existing migration pattern: ALTER TABLE errors ignored for idempotency
• event_log metadata is a JSON TEXT column for flexible structured data
• Pagination follows offset/limit pattern (no cursor — SQLite is simple enough)
• Event log pruning can be called from a cron job later (Phase 8)

Review Checklist

• All tasks completed
• Code follows project conventions
• No unintended side effects
• Build passes
• Tests pass (new + existing)

Handoff to Next Phase