Study Constellation
Visualize your daily study goals as a star map. Complete tasks to light up your personal constellation in a stunning cosmic sky.
Study Constellation: Architectural Blueprint, Data Structures & Engineering Decisions
An exhaustive systems architecture specification detailing the mathematical graph topology, 2D rasterization rendering pipeline, procedural Web Audio synthesis engine, and mathematical color distribution underpinning the Study Constellation daily focus visualizer.
1. Data Structures and Algorithms
At the operational core of Study Constellation is a decoupled topological graph structure combined with a continuous affine coordinate projection pipeline. Astronomical figures (such as Aquila, Phoenix, Lyra, and Cygnus) cannot be represented as static pixel bitmaps because user displays range from compact 360-pixel mobile screens to 4K ultra-wide desktop monitors.
To resolve this, constellations are defined as normalized unit-space graphs where each star node is a vertex with normalized coordinates (nx, ny) ∈ [0.0, 1.0] and astronomical magnitude weights. Relational skeletal bones are encoded as an unweighted undirected edge list:
// Constellation Normalized Graph Definition
const CONSTELLATIONS = {
aquila: {
name: "Aquila",
nodes: [
{ x: 0.50, y: 0.40, name: "Altair (Alpha)", mag: 1.4 },
{ x: 0.48, y: 0.28, name: "Tarazed (Gamma)", mag: 1.1 },
{ x: 0.52, y: 0.52, name: "Alshain (Beta)", mag: 1.1 },
{ x: 0.28, y: 0.35, name: "Deneb el Okab (Zeta)", mag: 1.0 },
{ x: 0.72, y: 0.42, name: "Tseen Foo (Theta)", mag: 1.0 }
],
edges: [
[1, 0], [0, 2], [3, 0], [0, 4]
]
}
};
// Affine Coordinate Projection Pipeline
function projectStarCoordinates(node, viewportWidth, viewportHeight, camera) {
const centerX = viewportWidth / 2;
const centerY = viewportHeight / 2;
const baseScale = Math.min(viewportWidth, viewportHeight) * 0.75 * camera.zoom;
// Linear transformation from unit [0, 1] space to screen pixel space
const screenX = centerX + (node.x - 0.5) * baseScale + camera.x;
const screenY = centerY + (node.y - 0.5) * baseScale + camera.y;
return { screenX, screenY };
}Why This Technique Was Chosen
Normalizing coordinates to a unit interval [0, 1] guarantees geometric invariant scaling. When the viewport resizes or the user changes device orientation, the constellation maintains proportional harmony without recalculating aspect ratio distortions. Furthermore, projecting with camera offsets allows pan and zoom operations to execute via simple scalar arithmetic rather than mutating the underlying data model.
Which Alternatives Exist
- Hardcoded Absolute Pixel Coordinates: Storing fixed pixel coordinates requires brittle CSS media queries and multiple coordinate sets, breaking responsiveness across non-standard viewports.
- Force-Directed Layout Simulations (e.g. Fruchterman-Reingold / D3-force): Dynamic spring-electrical simulations continuously compute repulsive and attractive forces. While engaging for unstructured data, force simulations fail to preserve recognizable mythological constellations, causing stars to drift into chaotic clusters.
- SVG Vector Graphs: Rendering nodes and links as SVG DOM elements provides resolution independence, but imposes heavy DOM tree serialization overhead during real-time 60 FPS particle shockwave bursts.
How It Can Be Scaled
For sky maps containing thousands of astronomical stars or community-contributed constellations, the linear search collision algorithm (O(N) distance checking) can be upgraded to an O(log N) Quadtree or spatial hash grid. User-added tasks beyond the preset archetype skeleton can utilize constrained Delaunay triangulation to dynamically connect new stars to the nearest existing nodes without visual edge crossings.
2. Performance Decisions
Delivering a seamless 60 frames per second graphical environment within a single self-contained HTML file demands rigorous avoidance of browser layout thrashing, efficient memory allocation, and zero garbage collection pauses.
// In-Place Particle Integration Loop
function updateParticlePhysics(particles, deltaTime) {
const viscousDrag = 0.96;
// Reverse loop permits safe in-place element removal via splice
for (let i = particles.length - 1; i >= 0; i--) {
const p = particles[i];
p.life -= p.decay;
if (p.life <= 0) {
particles.splice(i, 1);
continue;
}
// Semi-implicit Euler integration
p.x += p.vx * deltaTime;
p.y += p.vy * deltaTime;
p.vx *= viscousDrag;
p.vy *= viscousDrag;
}
}Why This Technique Was Chosen
Canvas 2D rasterization executes on an isolated GPU-accelerated drawing buffer, bypassing the browser's Document Object Model, style recalculations, and layout trees. Iterating backward through the particle array allows direct in-place array splices without index skipping or intermediate array allocations. This eliminates memory churn and prevents unpredictable garbage collection latency spikes during visual supernova explosions.
Which Alternatives Exist
- CSS Keyframe DOM Animations: Animating hundreds of star nodes and explosion particles via individual
<div>elements forces the browser compositor to manage hundreds of independent graphic layers, triggering high GPU VRAM consumption and thermal throttling on mobile devices. - WebGL / Three.js 3D Pipeline: WebGL offers massive parallel particle throughput, but introduces an initial 600KB+ bundle weight, shader compilation latency, and complex context management that conflicts with single-file zero-dependency architectural rules.
How It Can Be Scaled
To scale from hundreds to tens of thousands of active particles, dynamic JavaScript object allocations can be replaced with a contiguous Float32Array typed array backing store (Structure of Arrays). By rendering via an OffscreenCanvas worker thread, the physics simulation and rasterization loop can run entirely off the main UI thread, ensuring zero frame drops even under intense CPU load.
3. Design and Color Architecture
In accordance with the Zamansız Tasarım Prensipleri (Timeless Design Constitution), visual design cannot rely on arbitrary aesthetic guesswork. Every color, elevation tier, and typography ratio is mathematically derived using HSL color space coordinates and modular scales.
/* Mathematical HSL Color System — 60-30-10 Rule */
:root {
/* 60% Base Foundation: Interstellar Void (Low Saturation <= 45%, L <= 8%) */
--bg-base: hsl(232, 44%, 7%);
/* 30% Surface Architecture: Frosted Nebula Glass */
--bg-surface: hsl(235, 32%, 12%);
--bg-surface-elevated: hsl(235, 28%, 16%);
/* 10% Accents: Astrophysical Spectral Classes */
--star-o-blue: hsl(198, 96%, 62%); /* Deep Work (O-Type Supergiant) */
--star-g-gold: hsl(42, 96%, 62%); /* Spaced Review (G-Type Giant) */
--star-f-emerald: hsl(156, 88%, 56%); /* Code Practice (F-Type Nova) */
--star-m-violet: hsl(276, 92%, 68%); /* Research Theory (M-Type Pulsar) */
}Why This Technique Was Chosen
HSL (Hue, Saturation, Lightness) decouples chromatic identity from luminance. This guarantees that contrast ratios between interactive foreground text and dark background surfaces consistently exceed the WCAG AA minimum requirement of 4.5:1. Pure black (#000000) and pure white (#ffffff) are strictly prohibited; infusing subtle oceanic-indigo saturation into dark surfaces mimics natural atmospheric starlight diffusion, eliminating user eye fatigue during night study sessions.
Which Alternatives Exist
- sRGB / Hexadecimal Palette Declarations: Hex codes (e.g.
#12162a) obscure perceptual relationships, making programmatic shading, glow modulation, and alpha compositing difficult to calculate dynamically. - Pre-generated CSS Utility Libraries: External CSS utility classes inflate file size with unused definitions and fail to adapt dynamically to astrophysical spectral requirements.
How It Can Be Scaled
The color engine can be expanded into the modern W3C CSS Color Module Level 4 oklch() color space. OKLCH provides uniform perceived chroma across wide-gamut displays (Display P3), preventing blue and violet spectral stars from clipping or shifting hue when brightness transitions occur during particle emissions.
4. Anti-Pattern Warnings
When developing browser-based graphical and acoustic applications, developers routinely succumb to subtle design and implementation traps that compromise security, battery life, and cross-platform compatibility:
// ANTI-PATTERN: Eager AudioContext Creation
// const audio = new AudioContext(); // Causes console warning & blocked state!
// PROPER PATTERN: Interaction-Gated Lazy Audio Context
class ResilientAudioEngine {
constructor() {
this.ctx = null;
}
ensureRunning() {
if (!this.ctx) {
const AudioCtx = window.AudioContext || window.webkitAudioContext;
this.ctx = new AudioCtx();
}
if (this.ctx.state === "suspended") {
this.ctx.resume();
}
return this.ctx;
}
}Trap 1: Violating Browser Autoplay Audio Policies
Why it happens: Developers instantiate audio graphs during initial script parsing.
Impact: Modern browsers suspend the audio context and log console security warnings.
Mitigation: Defer all AudioContext creation and resume() calls until an explicit pointer or keyboard gesture is verified.
Trap 2: Layout Thrashing via DOM Hover Polling
Why it happens: Querying bounding rects (getBoundingClientRect()) inside mousemove listeners.
Impact: Forces synchronous layout reflows on every pointer movement, degrading 60 FPS canvas performance to stuttering 20 FPS.
Mitigation: Cache viewport dimensions during window resize events and compute canvas coordinates purely through Euclidean distance calculations.
Trap 3: Unmanaged Web Audio Node Accumulation
Why it happens: Triggering synthesized sound chimes without calling stop() or disconnecting graph nodes.
Impact: Orphaned oscillators and gain nodes remain in memory, slowly consuming audio hardware buffers and introducing audio latency.
Mitigation: Schedule strict exponential volume decay ramps and connect an onended callback to disconnect and garbage-collect audio nodes.
5. Alternative Approaches
Evaluating contrasting architectural paradigms contextualizes why a native Canvas 2D and Web Audio API architecture was selected over competing modern frameworks:
A. Pure Canvas 2D vs. Three.js / WebGL
Canvas 2D: Zero dependencies, instant loading on restricted cellular networks, trivial state serialization, and universal mobile compatibility. Ideal for clean 2D celestial charting.
Three.js / WebGL: Delivers true 3D orbital mechanics, volumetric shader clouds, and millions of GPU particles, but introduces a 600KB+ framework payload, shader compilation latency, and significant battery drain.
B. Single-File Architecture vs. Component Bundlers (Vite/React)
Single-File Vanilla HTML/JS: Extreme portability, zero build step, no npm security vulnerabilities, and infinite archival longevity. Perfect for micro-tools and privacy-conscious local utilities.
Framework Bundlers (Vite + React): Provides declarative UI components, type safety via TypeScript, and robust ecosystem packages, but introduces complex build pipelines, dependency rot, and multiple asset requests.
C. LocalStorage vs. IndexedDB vs. Cloud Database
LocalStorage: Synchronous, zero-latency access with tiny storage footprint suitable for daily task states and user preferences.
IndexedDB: Asynchronous storage capable of holding megabytes of historical sky telemetry, but introduces complex transaction handling for simple key-value needs.
Cloud Backend (Firebase / Supabase): Enables multi-device real-time sync and social constellation sharing, but requires network connectivity, authentication friction, and recurring infrastructure costs.
Recommended Enterprise Evolution
For enterprise or multi-user scaling, the ideal trajectory follows progressive enhancement: preserve the single-file Canvas 2D engine as a resilient, instant offline baseline, while providing opt-in WebSync via decentralized CRDTs (Conflict-free Replicated Data Types) for multi-device constellation collaboration.