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
