Axis/Seasons model (future VR notes)

• Per-frame orientation via solar zenith: φ = δ⊙; longitude from apparent sidereal time. Seasons/lighting are correct (solstices φ≈±ε, equinoxes φ≈0).
• We don’t persist an inertial axis vector to Polaris; this is sufficient for visuals. If needed later, add earthAxisNode in inertial space with precession/nutation and diurnal angle θ⊕.

Spiritual astronomy platform combining high-precision astronomical calculations with 3D visualization, WebAssembly performance, and Telegram community integration.

StarsCalendars is a high-performance spiritual astronomy platform that provides:

• 🌌 Real-time 3D Visualization: Cinematic quality astronomical scenes using Babylon.js 8
• ⚡ WebAssembly Calculations: High-precision ephemeris calculations compiled to WASM
• 📱 Telegram Integration: Community-driven authentication and premium features
• 🌍 Global Localization: 10-language support with cultural adaptations
• 🏧 Clean Architecture: Domain-driven design with clear separation of concerns

• Rust 1.92.0+ with Cargo edition 2024
• Axum web framework with WebSocket support
• PostgreSQL with SQLX for compile-time query validation
• Teloxide for Telegram Bot API integration
• JWT RS256 authentication with custom claims

• TypeScript 5.9 with strict type checking
• Babylon.js 8 (major pin; latest 8.x at build time) for 3D astronomical visualization
• Vite 7 build system with WASM integration
• React 19 with latest features
• Fluent for internationalization (ICU MessageFormat)

• Rust compiled to WebAssembly
• Zero-copy data transfer via Float64Array
• O(1) горячий путь for real-time calculations
• Thread-local buffers for performance optimization
• Output (bundler target) is written to frontend/src/wasm-astro/ as starscalendars_wasm_astro.js + *_bg.wasm
• Use left-handed Babylon system (default). Scientific coordinates remain RH (WASM). Apply single RH→LH Z flip in the scene when assigning positions; no flips in WASM bridge
• Single-call per frame: compute_state(jd) returns 27 f64 values (STATE, append-only):
  • Base scene slots [0..14]: Sun zeros [0..2], Moon distance AU [3], Earth RA/Dec/dist AU [4..6], Solar zenith lon/lat (east+, rad) [7..8], sublunar lat/lon (rad, east+) [9..10], Earth-local unit vector to Moon [11..13], apparent sidereal time rad [14].
  • Appended zodiac/events slots [15..26]: Sun/Moon ecliptic long/lat, illumination, elongation, zodiac indices (tropical+sidereal MVP=J2000), node/perigee longitudes, phase8 id (see wasm-astro/src/lib.rs doc-comment).
  • Sun slots [0..2] are zeros by design (Sun fixed at origin).
  • Event timing helper: next_winter_solstice_from(jd_utc_start) — off-frame only; high-precision λ_app(t)=270° solver (FK5 + aberration + nutation, TT↔UTC via TAI−UTC+32.184s), returns JD UTC.
• Zenith marker placement is canonical and must not be altered:
  • Use WASM radians directly; no degree conversions or constants
  • Local Earth-space spherical: phi=(π/2)-lat, theta=(-lon_east_rad)+π
  • Pivot orientation: pivot.y = -((-lon_east_rad)+π), pivot.z = lat, pivot.x = lat; Earth mesh rotations remain zero
  • Moon orbit must follow pivot tilt/azimuth

Контракт постоянно расширяется — обертка пишется с нуля под нужды сцены.

Назначение каждого слота STATE для сцены:

При расширении:

• Добавлять новые слоты в конец буфера
• Не менять индексы существующих
• Синхронизировать: tz.md, CLAUDE.md, .cursorrules, init.ts, BabylonScene.tsx, agents

Планируемые расширения:

• next_summer_solstice_from, next_vernal_equinox_from, next_autumnal_equinox_from
• next_orion_alignment_from — синхронизация Ориона с СЮН (Татев)
• Visual tidal lock для Луны

• All scene textures are served from frontend/public/textures and available at runtime under /textures/...
• Skybox: /textures/universe/universe_[px,py,pz,nx,ny,nz].jpg
• Earth: /textures/earth-diffuse.jpg, /textures/earth-height.png
• Moon: /textures/moon.jpg, /textures/moon_bump.jpg, /textures/moon_spec.jpg
• Stars: /textures/star.png

• Dioxus 0.7 fullstack framework for auth/profile/admin
• Pure Telegram authentication (no passwords)
• Subscription verification via getChatMember API
• GUI: Babylon GUI for date/quantum date; a single #stats div overlay for FPS; no other HTML overlays

• Two camera modes exist in the scene: cameraTarget = 'earth' | 'moon' (see frontend/src/scene/BabylonScene.tsx).
• Earth preset (startup + 🌍 button): positions camera above an approximated user location on Earth (timezone→longitude), using a two-phase ArcRotate apply (detachControl → setTarget/setPosition → render → lockedTarget → attachControl → render) and resets limits.
• Moon preset (🌙 button): sets camera position to Earth center (earthPivot.position) and target to Moon world position (moonMesh.getAbsolutePosition()), then locks alpha/beta (rotation) and leaves only zoom (radius limits derived from current radius).
• Important: the scene uses only one HTML overlay element: #stats and in prod mast commented code. Any extra hint like “РАСШИФРОВКА ДНЯ в @elioncalendar” must be rendered inside scene top on quantum time.

• NT (quantum date) moved from JS to WASM:
  • get_quantum_time_components(epoch_ms, timezone_offset_minutes) returns [d_in_decade, decade_index, year_index] (f64*3 pointer; zero-copy read in TS)
  • Identical semantics to legacy JS (special days, fixed durations), but centralized and reusable
  • UI updates once per minute in idle to avoid frame cost

starscalendars/
├── astro-rust/        # 🔒 ASTRONOMICAL LIBRARY (READ-ONLY!) - DO NOT MODIFY
├── frontend/          # TypeScript + Vite + Babylon.js
├── wasm-astro/        # Rust WASM: эфемеридное ядро  
├── backend/           # Axum HTTP/WS, PostgreSQL, Telegram, JWT
├── dioxus-app/        # Dioxus 0.7 fullstack для auth/profile/admin
├── libs/
│   ├── domain/        # Чистые типы и бизнес-правила
│   ├── app/           # Use-cases, портовые интерфейсы
│   └── infra/         # Клиенты PostgreSQL/Telegram/Cache
└── ops/               # Миграции, Helm/compose, CI/CD - МЫ НЕ ИСПОЛЬЗУЕМ ДОКЕР И РУКАМИ РАЗВОРАЧИВАЕМ НА СЕРВЕР Almalinux 9.4 уже скомпилированны фронт и только сарвер компилируем на своем сервере линукс для продакшна к которому копируем скомпилированный фронт!!!

The astro-rust/ folder contains the local copy of the astronomical calculation library with critical bug fixes:

• 🔒 DO NOT MODIFY any files in this folder
• 📚 Contains: VSOP87, ELP-2000/82 implementations with decimal_day and lunar equation fixes
• 🎯 Usage: Referenced via astro = { path = "./astro-rust" } in Cargo.toml
• ⚠️ WARNING: Any modifications will break astronomical precision and corrupt calculations

Референсная сцена больше не используется как источник истины и удалена из процесса. Все правила и формулы закреплены в текущей документации и в коде сцены.

• Rust 1.92.0+ (automatically managed via rust-toolchain.toml)
• Node.js 20+ and pnpm 9+
• PostgreSQL 17+
• Redis (for caching)
• wasm-pack for WebAssembly builds

# Clone the repository
git clone <repository-url>
cd starscalendars

# Install dependencies
pnpm install

# Build WASM astronomical core
pnpm run build:wasm

# Run quality checks
make quality-check

# Start frontend only (build WASM first and run Vite)
pnpm -w run dev:frontend-only

# Build all workspaces
pnpm run build

# Build specific components
pnpm run build:frontend    # Vite build for frontend
pnpm run build:wasm        # wasm-pack build for astronomical core
pnpm run build:dioxus      # Dioxus build for auth app
cargo build --release      # Axum server production build

# Development servers
pnpm run dev               # Start all development servers
pnpm run dev:frontend      # Vite dev server only
cargo run -p starscalendars-backend  # Axum server with hot reload

This project enforces zero-tolerance for anti-patterns and maintains strict quality standards:

# Run all quality checks
make quality-check

# Individual checks
make anti-patterns         # Scan for forbidden patterns
make clippy               # Strict Clippy lints
make security             # Security validation
make arch                 # Architecture compliance
make wasm-perf            # WASM performance validation

# Pre-commit validation
make pre-commit

🔥 СТРОГО ЗАПРЕЩЕННЫЕ ПАТТЕРНЫ В WASM ОБЕРТКЕ:

• ❌ Mock-данные любого вида - даже временные или для тестов
• ❌ Кастомные астрономические формулы не из astro-rust библиотеки
• ❌ Hardcoded константы планетарных позиций или орбитальных элементов
• ❌ Прямые математические расчеты вместо вызовов astro-rust функций
• ❌ eval() - 🚨 КРИТИЧЕСКАЯ уязвимость безопасности
• ❌ Изменение кода в ./astro-rust/ - папка read-only
• ❌ Частичное покрытие API - должны быть ВСЕ функции библиотеки
• ❌ Отсебятина в расчетах - только чистые astro-rust вызовы

✅ ОБЯЗАТЕЛЬНО ИСПОЛЬЗОВАТЬ:

• ТОЛЬКО функции из astro-rust для астрономических расчетов
• Единый вызов compute_state(jd) на кадр (зенит уже в буфере)
• Исключение производительности: координаты Солнца в буфере заполняются нулями (сцена держит Солнце в (0,0,0)); вычисление солнечной позиции в горячем пути опущено намеренно
• Реальные эфемеридные данные, коррекции нутации/прецессии при необходимости

• ❌ unwrap(), expect(), panic!() - Use Result<T, E> everywhere
• ❌ HashMap::new(), Vec::new() - Use with_capacity() for performance
• ❌ as conversions - Use TryFrom for safe type conversion
• ❌ Multiple WASM calls per frame - Only one compute_state(t) allowed
• ❌ .await in loops - Violates real-time performance requirements

• O(1) горячий путь: Exactly one WASM call per frame
• 60 FPS: Cinematic quality 3D rendering
• <3s: Page load time target
• 10,000+: Concurrent Telegram bot users
• <500ms: Telegram bot response time

1. Domain Layer: Pure business logic, no infrastructure dependencies
2. Application Layer: Use cases and port interfaces
3. Infrastructure Layer: External service implementations
4. Delivery Layer: HTTP/WS handlers, UI components

• Pre-allocated Collections: All HashMap and Vec use with_capacity()
• Zero-Copy WASM: Float64Array view for astronomical data
• Thread-Local Buffers: Eliminate allocations in hot paths
• Compile-Time Validation: SQLX macros for database queries

• Telegram-Only Auth: No traditional passwords
• JWT RS256: Cryptographically secure tokens
• Subscription Verification: Real-time channel membership checks
• Rate Limiting: Anti-abuse protection

10 Language Support with cultural adaptations:

Tier 1: Russian, English, Chinese, Spanish, Hindi
Tier 2: Portuguese, German, French, Japanese
Tier 3: Armenian

• Fluent L10n: ICU MessageFormat standard
• Cultural Sensitivity: Spiritual community considerations

✅ Phase 0.1-0.2: Инфраструктура и архитектура (ЗАВЕРШЕНО)

• Монорепозиторий с pnpm workspaces
• Clean Architecture (domain/app/infra слои)
• Quality Guardian система (77% готовности)
• Rust 1.92.0+ compliance с zero anti-patterns
• CI/CD pipeline, VS Code интеграция

✅ Phase 1.1: Астрономическое ядро (ЗАВЕРШЕНО)

• WASM модуль: thread-local буферы, O(1) compute_state() (zenith included)
• Backend: Axum 0.8, JWT RS256, WebSocket auth
• Frontend: TypeScript 5.9, React 19, WASM интеграция
• Infrastructure: wasm-pack, pnpm workspace, сборка успешна

✅ Frontend Build: 17.48s with Vite 7.1.1 (Target: <20s)
✅ Bundle Size: 7.4MB total (5.3MB Babylon.js, 1.6MB WASM)
✅ WASM Module: 1.6MB compiled with astro-rust
✅ Zero Anti-Patterns: Rust 1.92.0+ compliant
✅ TypeScript: 100% strict typing (5.9.2)
✅ React: 19.1.1 latest features

🚀 Phase 1.2: 3D Визуализация (В ПРОЦЕССЕ)

• Babylon.js 8 deps установлены
• Vite 7 + React 19 + TypeScript 5.9 стек готов
• WASM-Frontend интеграция complete (z‑flip в мосте)
• GUI: Babylon GUI для дат, #stats overlay для FPS
• Пивоты Земли/Луны, true anomaly в поворотах, зенит‑маркер по формуле референса

• ✅ wasm-pack установлен и работает
• ✅ Frontend компилируется успешно (5.06s)
• ✅ WASM-JS интеграция функционирует
• ✅ Zero anti-patterns соблюдены
• ✅ Performance targets достигнуты

• Сублинарная точка (зенит Луны) вычисляется из RA/Dec Луны + видимого сидерического времени (AST); совпадает с внешними источниками
• Позиция Луны синхронизирована с маркером: используется тот же вектор (RA/Dec+AST → локальный земной вектор → мир), устранён постоянный сдвиг долготы
• Солнце статично в (0,0,0); слоты [0..2] STATE = 0

• Расширить compute_state(jd) и вернуть в STATE предрасчёт, чтобы сцена не делала тригонометрию:
  • lunar_ra_rad, lunar_dec_rad, apparent_sidereal_time_rad
  • sublunar_lon_east_rad, sublunar_lat_rad
  • Единичный Earth-local вектор направления на Луну (или эквивалент в согласованной СК)
  • Ровно 1× compute_state на кадр; без дополнительных wasm-вызовов
• Реализовать визуальный tidal lock Луны: поворачивать её меш так, чтобы «одна сторона к Земле» (без либраций на этом этапе)

1. Run quality checks: make quality-check before any commit
2. Follow Clean Architecture: Respect layer boundaries
3. Zero anti-patterns: Strict enforcement of performance patterns
4. Comprehensive testing: Unit tests for all business logic
5. Documentation: Clear, technical documentation

# Create feature branch
git checkout -b feature/astronomical-calculations

# Make changes following quality standards
# ...

# Validate before commit
make pre-commit

# Commit with descriptive message
git commit -m "feat: implement high-precision ephemeris calculations

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>"

• Technical Specification: Detailed system architecture (canonicalized)
• Product Requirements: Feature specifications
• Quality Rules: Enforced coding standards
• Build System: Quality assurance automation
• Canonical Context Bootstrap: Single source of truth for agents

UNLICENSED - Proprietary spiritual astronomy platform

Built with reverence for cosmic wisdom and technical excellence 🌟

Connecting spiritual seekers to astronomical knowledge through high-performance technology