Nyx — Dev Log

Date: 2026-06-06
Time: ~5+ hours
Focus: Backend architecture, system boundaries, documentation
Use of Ai: Only used to polish the devlog from my drafts.

Summary

This session was split into two parts:

~4+ hours: architectural thinking (partially unrecorded due to lapse)
~1 hour: Markdown documentation and formalization

The main output was system design, not implementation.

Phase 1 — Architecture (~4+ hours, partially lost)

Designed Nyx as a Spring Boot backend with strict epistemic constraints.

Key decisions:

Backend is the authoritative system layer
Frontend is read-only
Domain-first structure replaces controller/service/repo layering
Core entities:
- location
- index
- snapshot
- comparison

Epistemic boundary defined

Nyx only:

derives normalized light indices from satellite data
performs comparative geographic reasoning
maps to heuristic scales
produces order-of-magnitude outputs

Nyx does NOT:

simulate sky conditions
predict human perception
output observational truth

System design additions

PostgreSQL + PostGIS persistence layer
Flyway migrations
JPA/Hibernate ORM
Event-driven pipeline (replacing PipelineRunner)
Observability (metrics, tracing, logging)
Security layer (rate limiting, API keys)

Phase 2 — Documentation (~1 hour)

Converted design into structured Markdown system.

Added:

CLAIM_CHARTER
METHODOLOGY
DATA_SOURCES
LIMITATIONS
GLOSSARY
ONTOLOGY
VALIDATION

Architecture decisions:

ADR system introduced
OpenAPI-first API design
Domain-driven backend structure finalized
Infrastructure + deployment roadmap defined

Outcome

Nyx now has:

Spring Boot backend architecture
strict claim boundary system
domain-first design
event-driven pipeline plan
persistence + infrastructure design
full documentation framework

Next steps

Scaffold backend project
Implement ClaimGuard
Define OpenAPI spec
Build persistence layer
Start ADR-001