ADR 001: Core Architecture Stack
Status
Section titled “Status”Accepted
Context
Section titled “Context”Lakea is a scientific data visualization project with multiple goals:
- Demonstrate maintainable code that survives developer turnover
- Create interactive visualizations of large astronomical datasets
- Serve as a technical portfolio for research infrastructure positions
The architecture must support:
- Multiple applications sharing common code
- Mix of static pages and interactive visualizations
- Documentation that stays current with code
- Free or low-cost deployment
- Standard scientific visualization tools (D3, Three.js)
Decision
Section titled “Decision”Monorepo: NX + pnpm
Section titled “Monorepo: NX + pnpm”Chosen over: Turborepo, Lerna, npm workspaces alone
Rationale:
nx affectedcommands enable efficient CI for large codebases- Incremental builds reduce iteration time
- Built-in generators for consistent project scaffolding
- Plugin ecosystem for TypeScript, Vite, ESLint
- pnpm provides fast installs and strict dependency resolution
Language: TypeScript strict
Section titled “Language: TypeScript strict”Rationale:
- Enforced contracts between packages
- Self-documenting code through types
- Refactoring confidence
- IDE support for large codebases
Apps: Astro + React islands
Section titled “Apps: Astro + React islands”Chosen over: Next.js, Remix, pure React SPAs
Rationale:
- Static-first matches our deployment goals (Cloudflare Pages free tier)
- React islands allow interactive visualizations where needed
- MDX support for documentation-heavy content
- Zero JS shipped by default
- Framework-agnostic—can use React, Vue, or vanilla JS as needed
Documentation: Starlight
Section titled “Documentation: Starlight”Chosen over: Docusaurus, VitePress, custom solution
Rationale:
- Built on Astro (consistent with apps)
- MDX support with component integration
- Excellent defaults for technical documentation
- Sidebar auto-generation from file structure
Visualization: D3.js + Three.js
Section titled “Visualization: D3.js + Three.js”Rationale:
- D3 is the standard for scientific 2D visualization
- Three.js is the standard for WebGL 3D
- Both are framework-agnostic
- Large community and extensive examples
Testing: Vitest
Section titled “Testing: Vitest”Chosen over: Jest
Rationale:
- Native ESM support
- Vite-compatible (same config as apps)
- Fast execution
- Compatible with Jest APIs for familiarity
Deployment: Cloudflare Pages
Section titled “Deployment: Cloudflare Pages”Chosen over: Vercel, Netlify, GitHub Pages
Rationale:
- Free tier is generous for open source
- Edge deployment for global performance
- Preview deploys for PRs
- Workers available if we need edge compute
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Unified tooling across all projects
- Static-first keeps costs at zero
- Strong typing catches errors early
- Standard viz libraries mean transferable skills
- Documentation lives with code
Negative
Section titled “Negative”- NX has learning curve for contributors
- Astro ecosystem smaller than Next.js
- Must maintain framework-agnostic packages
- Some features require more manual setup than opinionated frameworks
- NX versioning can cause breaking changes (mitigated by lockfile)
- Astro is newer, API may evolve (mitigated by using stable features only)