Project Architecture

The project is modularized across independent, specialized repositories:

  • umi-time/spec — The canonical, self‑contained standard defining the Umi‑Time model, including universal time representation, local interpretation, solar context, mathematical formulas, and canonical formats.
  • umi-time/www — The primary public website, the Manifesto, and the presentation layers (Clock, Map, Geometry). It embeds the spec repository dynamically via a Git submodule.
  • umi-time/umi-time-js — The reference JavaScript/TypeScript implementation library for core parsing, calculation, and rendering.

Contributing to the Specification Standard

Because the spec repository maintains the immutable standard, changes to formulas or core architectures follow a strict protocol. Typos, formatting bugs, or ambiguities can be submitted directly via an Issue in the spec repository. Architectural adjustments require community consensus on a Discussion thread prior to drafting a Pull Request.

Getting Started with the Website

To contribute to the website layout, documentation text, or interactive tools, clone the web repository locally:

git clone https://github.com/umi-time/www.git
cd www
git submodule update --init --recursive
npm install

Important First-Time Setup Note: Our astro.config.mjs features an automated asset sync script that mirrors submodule layouts and MathJax layouts into your active public/ tree. **You must run the compilation sequence at least once** to populate these asset structures properly before initializing your dev server:

npm run build

Once compiled, start Astro's local hot-reloading development loop:

npm run dev

Website Contributions

The primary public interface lives in the www repository and is powered by Astro. Impactful contributions include:

  • Improving documentation copy and text layout readability.
  • Resolving responsive design framework or styling bugs across viewports.
  • Enhancing interactive demonstrations, including analog clock, cartographic, and solar‑context visualizations.
  • Drafting new implementation examples, setup recipes, or technical tutorials.

Making Changes

Before opening a pull request on any repository:

  • Ensure TypeScript builds cleanly without errors
  • Run the repository test suite if applicable
  • Follow existing code style and naming conventions
  • Update documentation if your change affects a public API or interface behavior

Coding & Documentation Standards

  • Universal First: Keep the underlying time representation mapped strictly to UTC. Never write regional adjustments into Layer 1 data.
  • Layer Separation: Treat universal time, local interpretation, and solar context as distinct concerns. Changes in one layer should not modify another.
  • Presentation Agnostic: Interface logic should support analog, digital, textual, cartographic, and future presentation forms without making any single representation fundamental.
  • Zero JS Footprint by Default: The specification page parses static raw HTML elements server-side via Astro's set:html directive. Keep script inclusions tightly scoped.

Library Coding Standards

When contributing code to the umi-time-js core reference library, adhere to these architectural rules:

  • Use TypeScript for all core library code.
  • Prefer pure functions for solar geometry and time conversion calculations.
  • Keep the UmiTime engine immutable—all transformation methods must return new instances.
  • Document public methods explicitly with clear intent, parameter definitions, and geometric units.
  • Write comprehensive tests for any new local-interpretation, solar-context, coordinate-mapping, or astronomical calculation functions.
  • Ensure all formatting spec constants remain strictly synchronized with the canonical Umi‑Time standard.

Pull Requests

Every pull request should:

  • Build successfully inside its independent repository pipeline
  • Pass all validation checks and tests
  • Include updated documentation if needed
  • Reference related issues or discussions

Keep PRs focused. Small, well-scoped changes are significantly easier to review and merge.

Issues & Feature Requests

If you find a bug or want to propose a feature, open an issue on the specific repository matching the component.

Please include:

  • Clear reproduction steps
  • Expected vs actual behavior
  • Environment details (browser, OS, Node version)
  • Any relevant Umi‑Time input values or coordinates

Thank You

Umi‑Time is a voluntary, collaborative effort to refine how a connected species communicates about time. Whether you’re correcting an equation typo, translating document layouts, or constructing a client library, your help is deeply appreciated.

Documentation
Developer
Project