chore(release): prepare v0.1.0 release for main #16
@@ -0,0 +1,21 @@
|
|||||||
|
# build output
|
||||||
|
dist/
|
||||||
|
# generated types
|
||||||
|
.astro/
|
||||||
|
|
||||||
|
# dependencies
|
||||||
|
node_modules/
|
||||||
|
|
||||||
|
# logs
|
||||||
|
npm-debug.log*
|
||||||
|
yarn-debug.log*
|
||||||
|
yarn-error.log*
|
||||||
|
pnpm-debug.log*
|
||||||
|
|
||||||
|
|
||||||
|
# environment variables
|
||||||
|
.env
|
||||||
|
.env.production
|
||||||
|
|
||||||
|
# macOS-specific files
|
||||||
|
.DS_Store
|
||||||
Vendored
+4
@@ -0,0 +1,4 @@
|
|||||||
|
{
|
||||||
|
"recommendations": ["astro-build.astro-vscode"],
|
||||||
|
"unwantedRecommendations": []
|
||||||
|
}
|
||||||
Vendored
+11
@@ -0,0 +1,11 @@
|
|||||||
|
{
|
||||||
|
"version": "0.2.0",
|
||||||
|
"configurations": [
|
||||||
|
{
|
||||||
|
"command": "./node_modules/.bin/astro dev",
|
||||||
|
"name": "Development server",
|
||||||
|
"request": "launch",
|
||||||
|
"type": "node-terminal"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
@@ -0,0 +1,22 @@
|
|||||||
|
## Development
|
||||||
|
|
||||||
|
When starting the dev server, use background mode:
|
||||||
|
|
||||||
|
```
|
||||||
|
astro dev --background
|
||||||
|
```
|
||||||
|
|
||||||
|
Manage the background server with `astro dev stop`, `astro dev status`, and `astro dev logs`.
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
Full documentation: https://docs.astro.build
|
||||||
|
|
||||||
|
Consult these guides before working on related tasks:
|
||||||
|
|
||||||
|
- [Adding pages, dynamic routes, or middleware](https://docs.astro.build/en/guides/routing/)
|
||||||
|
- [Working with Astro components](https://docs.astro.build/en/basics/astro-components/)
|
||||||
|
- [Using React, Vue, Svelte, or other framework components](https://docs.astro.build/en/guides/framework-components/)
|
||||||
|
- [Adding or managing content](https://docs.astro.build/en/guides/content-collections/)
|
||||||
|
- [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/)
|
||||||
|
- [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/)
|
||||||
Symlink
+1
@@ -0,0 +1 @@
|
|||||||
|
AGENTS.md
|
||||||
@@ -0,0 +1,49 @@
|
|||||||
|
# Starlight Starter Kit: Basics
|
||||||
|
|
||||||
|
[](https://starlight.astro.build)
|
||||||
|
|
||||||
|
```
|
||||||
|
pnpm create astro@latest -- --template starlight
|
||||||
|
```
|
||||||
|
|
||||||
|
> 🧑🚀 **Seasoned astronaut?** Delete this file. Have fun!
|
||||||
|
|
||||||
|
## 🚀 Project Structure
|
||||||
|
|
||||||
|
Inside of your Astro + Starlight project, you'll see the following folders and files:
|
||||||
|
|
||||||
|
```
|
||||||
|
.
|
||||||
|
├── public/
|
||||||
|
├── src/
|
||||||
|
│ ├── assets/
|
||||||
|
│ ├── content/
|
||||||
|
│ │ └── docs/
|
||||||
|
│ └── content.config.ts
|
||||||
|
├── astro.config.mjs
|
||||||
|
├── package.json
|
||||||
|
└── tsconfig.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
|
||||||
|
|
||||||
|
Images can be added to `src/assets/` and embedded in Markdown with a relative link.
|
||||||
|
|
||||||
|
Static assets, like favicons, can be placed in the `public/` directory.
|
||||||
|
|
||||||
|
## 🧞 Commands
|
||||||
|
|
||||||
|
All commands are run from the root of the project, from a terminal:
|
||||||
|
|
||||||
|
| Command | Action |
|
||||||
|
| :------------------------ | :----------------------------------------------- |
|
||||||
|
| `pnpm install` | Installs dependencies |
|
||||||
|
| `pnpm dev` | Starts local dev server at `localhost:4321` |
|
||||||
|
| `pnpm build` | Build your production site to `./dist/` |
|
||||||
|
| `pnpm preview` | Preview your build locally, before deploying |
|
||||||
|
| `pnpm astro ...` | Run CLI commands like `astro add`, `astro check` |
|
||||||
|
| `pnpm astro -- --help` | Get help using the Astro CLI |
|
||||||
|
|
||||||
|
## 👀 Want to learn more?
|
||||||
|
|
||||||
|
Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
// @ts-check
|
||||||
|
import { defineConfig } from 'astro/config';
|
||||||
|
import starlight from '@astrojs/starlight';
|
||||||
|
|
||||||
|
// https://astro.build/config
|
||||||
|
export default defineConfig({
|
||||||
|
integrations: [
|
||||||
|
starlight({
|
||||||
|
title: 'My Docs',
|
||||||
|
social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }],
|
||||||
|
sidebar: [
|
||||||
|
{
|
||||||
|
label: 'Guides',
|
||||||
|
items: [
|
||||||
|
// Each item here is one entry in the navigation menu.
|
||||||
|
{ label: 'Example Guide', slug: 'guides/example' },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: 'Reference',
|
||||||
|
items: [{ autogenerate: { directory: 'reference' } }],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
}),
|
||||||
|
],
|
||||||
|
});
|
||||||
@@ -0,0 +1,17 @@
|
|||||||
|
{
|
||||||
|
"name": "docs",
|
||||||
|
"type": "module",
|
||||||
|
"version": "0.0.1",
|
||||||
|
"scripts": {
|
||||||
|
"dev": "astro dev",
|
||||||
|
"start": "astro dev",
|
||||||
|
"build": "astro build",
|
||||||
|
"preview": "astro preview",
|
||||||
|
"astro": "astro"
|
||||||
|
},
|
||||||
|
"dependencies": {
|
||||||
|
"@astrojs/starlight": "^0.41.3",
|
||||||
|
"astro": "^7.0.2",
|
||||||
|
"sharp": "^0.34.5"
|
||||||
|
}
|
||||||
|
}
|
||||||
Generated
+4323
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,3 @@
|
|||||||
|
allowBuilds:
|
||||||
|
esbuild: true
|
||||||
|
sharp: true
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill-rule="evenodd" d="M81 36 64 0 47 36l-1 2-9-10a6 6 0 0 0-9 9l10 10h-2L0 64l36 17h2L28 91a6 6 0 1 0 9 9l9-10 1 2 17 36 17-36v-2l9 10a6 6 0 1 0 9-9l-9-9 2-1 36-17-36-17-2-1 9-9a6 6 0 1 0-9-9l-9 10v-2Zm-17 2-2 5c-4 8-11 15-19 19l-5 2 5 2c8 4 15 11 19 19l2 5 2-5c4-8 11-15 19-19l5-2-5-2c-8-4-15-11-19-19l-2-5Z" clip-rule="evenodd"/><path d="M118 19a6 6 0 0 0-9-9l-3 3a6 6 0 1 0 9 9l3-3Zm-96 4c-2 2-6 2-9 0l-3-3a6 6 0 1 1 9-9l3 3c3 2 3 6 0 9Zm0 82c-2-2-6-2-9 0l-3 3a6 6 0 1 0 9 9l3-3c3-2 3-6 0-9Zm96 4a6 6 0 0 1-9 9l-3-3a6 6 0 1 1 9-9l3 3Z"/><style>path{fill:#000}@media (prefers-color-scheme:dark){path{fill:#fff}}</style></svg>
|
||||||
|
After Width: | Height: | Size: 696 B |
Binary file not shown.
|
After Width: | Height: | Size: 96 KiB |
@@ -0,0 +1,7 @@
|
|||||||
|
import { defineCollection } from 'astro:content';
|
||||||
|
import { docsLoader } from '@astrojs/starlight/loaders';
|
||||||
|
import { docsSchema } from '@astrojs/starlight/schema';
|
||||||
|
|
||||||
|
export const collections = {
|
||||||
|
docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
|
||||||
|
};
|
||||||
@@ -0,0 +1,142 @@
|
|||||||
|
# ADR-0001: Repository Structure
|
||||||
|
|
||||||
|
* **Status:** Accepted
|
||||||
|
* **Date:** 2026-07-12
|
||||||
|
* **Decision Makers:** LUNA Charts Maintainers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
LUNA Charts is designed as an open-source charting library with a strong focus on accessibility, maintainability, and long-term evolution.
|
||||||
|
|
||||||
|
The project consists of multiple concerns, including source code, documentation, examples, testing infrastructure, and continuous integration.
|
||||||
|
|
||||||
|
A repository structure was required that supports collaborative development while keeping the project easy to understand for contributors and maintainers.
|
||||||
|
|
||||||
|
The repository should also support future growth without requiring structural changes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision Drivers
|
||||||
|
|
||||||
|
The following factors influenced this decision:
|
||||||
|
|
||||||
|
* Maintainability
|
||||||
|
* Developer Experience
|
||||||
|
* Open Source Collaboration
|
||||||
|
* Modular Architecture
|
||||||
|
* Shared Tooling
|
||||||
|
* Consistent Build Process
|
||||||
|
* Long-Term Evolution
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Considered Alternatives
|
||||||
|
|
||||||
|
| Alternative | Description |
|
||||||
|
| ------------------------------------ | ---------------------------------------------------------------------------------- |
|
||||||
|
| Multiple repositories | Separate repositories for documentation, examples, and library packages. |
|
||||||
|
| Single repository without workspaces | One repository containing all files without workspace separation. |
|
||||||
|
| **Monorepo using pnpm Workspaces** | One repository containing all project artifacts with logical workspace separation. |
|
||||||
|
|
||||||
|
Multiple repositories were rejected because they increase maintenance effort, duplicate tooling, and complicate contribution workflows.
|
||||||
|
|
||||||
|
A single repository without workspaces was rejected because the project is expected to grow over time and benefits from a clear modular organization.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
LUNA Charts is implemented as a **pnpm-based monorepo**.
|
||||||
|
|
||||||
|
The repository contains all project artifacts, including:
|
||||||
|
|
||||||
|
* Source code
|
||||||
|
* Documentation
|
||||||
|
* Storybook
|
||||||
|
* Examples
|
||||||
|
* Architecture documentation
|
||||||
|
* Architecture Decision Records (ADRs)
|
||||||
|
* CI/CD configuration
|
||||||
|
|
||||||
|
The repository is organized into logical workspaces.
|
||||||
|
|
||||||
|
```text
|
||||||
|
luna-charts/
|
||||||
|
│
|
||||||
|
├── packages/
|
||||||
|
│ └── luna-charts/
|
||||||
|
│
|
||||||
|
├── apps/
|
||||||
|
│ ├── storybook/
|
||||||
|
│ └── docs/
|
||||||
|
│
|
||||||
|
├── docs/
|
||||||
|
│ ├── architecture/
|
||||||
|
│ └── adr/
|
||||||
|
│
|
||||||
|
├── examples/
|
||||||
|
│
|
||||||
|
└── .github/
|
||||||
|
```
|
||||||
|
|
||||||
|
Internally, the library is organized into architectural modules such as:
|
||||||
|
|
||||||
|
* Core
|
||||||
|
* Charts
|
||||||
|
* Themes
|
||||||
|
* Utilities
|
||||||
|
|
||||||
|
These modules are implementation details and are **not** exposed as individual npm packages.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
|
||||||
|
A monorepo provides a single source of truth for the entire project.
|
||||||
|
|
||||||
|
All contributors work within the same repository using a shared toolchain, coding standards, testing infrastructure, and documentation.
|
||||||
|
|
||||||
|
Using **pnpm Workspaces** enables clear separation of responsibilities while avoiding duplicated dependencies and configuration.
|
||||||
|
|
||||||
|
This structure supports the project's architecture-first approach and simplifies future expansion.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
### Positive
|
||||||
|
|
||||||
|
* Single source of truth
|
||||||
|
* Simplified onboarding for contributors
|
||||||
|
* Shared tooling and configuration
|
||||||
|
* Consistent CI/CD pipeline
|
||||||
|
* Easier dependency management
|
||||||
|
* Centralized documentation
|
||||||
|
* Scalable project organization
|
||||||
|
|
||||||
|
### Negative
|
||||||
|
|
||||||
|
* Larger repository size
|
||||||
|
* Contributors clone the complete repository
|
||||||
|
* Workspace configuration introduces a small amount of additional complexity
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related TOGAF Phases
|
||||||
|
|
||||||
|
* Architecture Vision (Phase A)
|
||||||
|
* Technology Architecture (Phase D)
|
||||||
|
* Opportunities & Solutions (Phase E)
|
||||||
|
* Migration Planning (Phase F)
|
||||||
|
* Implementation Governance (Phase G)
|
||||||
|
* Architecture Change Management (Phase H)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
* LUNA Charts Architecture Wiki
|
||||||
|
* ADR-0002: Technology Stack
|
||||||
|
* pnpm Workspaces Documentation
|
||||||
@@ -0,0 +1,211 @@
|
|||||||
|
# ADR-0002: Technology Stack
|
||||||
|
|
||||||
|
* **Status:** Accepted
|
||||||
|
* **Date:** 2026-07-12
|
||||||
|
* **Decision Makers:** LUNA Charts Maintainers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
LUNA Charts is an open-source charting library designed to provide accessible, framework-agnostic, and strongly typed chart components.
|
||||||
|
|
||||||
|
The selected technology stack must support the architectural principles defined during the TOGAF Architecture Development Method (ADM), including:
|
||||||
|
|
||||||
|
* Accessibility by Design
|
||||||
|
* Framework Agnosticism
|
||||||
|
* Strong Type Safety
|
||||||
|
* Component-Based Architecture
|
||||||
|
* High Developer Experience
|
||||||
|
* Open Source Collaboration
|
||||||
|
* Long-Term Maintainability
|
||||||
|
|
||||||
|
Rather than selecting technologies based on popularity, each technology is evaluated according to its ability to support these architectural goals.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision Drivers
|
||||||
|
|
||||||
|
The following factors influenced the decision:
|
||||||
|
|
||||||
|
* Accessibility
|
||||||
|
* Framework Agnosticism
|
||||||
|
* Type Safety
|
||||||
|
* Developer Experience
|
||||||
|
* Maintainability
|
||||||
|
* Testability
|
||||||
|
* Documentation
|
||||||
|
* Open Source Collaboration
|
||||||
|
* Long-Term Evolution
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Considered Alternatives
|
||||||
|
|
||||||
|
| Technology Area | Considered Alternatives | Selected |
|
||||||
|
| ----------------------- | ----------------------------------------------- | ------------------ |
|
||||||
|
| Component Framework | React, Vue, Angular, Lit, StencilJS | **StencilJS** |
|
||||||
|
| Component Documentation | Storybook, Styleguidist | **Storybook** |
|
||||||
|
| Project Documentation | Docusaurus, VitePress, Starlight | **Starlight** |
|
||||||
|
| Package Manager | npm, Yarn, pnpm | **pnpm** |
|
||||||
|
| Unit Testing | Vitest, Jest | **Jest** |
|
||||||
|
| Browser Testing | Cypress, Playwright | **Playwright** |
|
||||||
|
| Accessibility Testing | Manual Testing Only, axe-core | **axe-core** |
|
||||||
|
| Code Formatting | Manual Formatting, Prettier | **Prettier** |
|
||||||
|
| Static Analysis | TSLint, ESLint | **ESLint** |
|
||||||
|
| Versioning | Manual Versioning, Semantic Release, Changesets | **Changesets** |
|
||||||
|
| Continuous Integration | GitLab CI, Azure Pipelines, GitHub Actions | **GitHub Actions** |
|
||||||
|
|
||||||
|
The selected technologies best support the project's architectural goals while remaining broadly adopted and well documented.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
The following technology stack is adopted for the implementation of LUNA Charts.
|
||||||
|
|
||||||
|
| Technology | Purpose |
|
||||||
|
| ------------------ | --------------------------------------------------- |
|
||||||
|
| **StencilJS** | Web Component development |
|
||||||
|
| **Storybook** | Interactive component documentation and development |
|
||||||
|
| **Starlight** | Project and architecture documentation |
|
||||||
|
| **TypeScript** | Strong typing and developer tooling |
|
||||||
|
| **pnpm** | Package management and workspace support |
|
||||||
|
| **Jest** | Unit testing |
|
||||||
|
| **Playwright** | Browser and interaction testing |
|
||||||
|
| **axe-core** | Accessibility validation |
|
||||||
|
| **ESLint** | Static code analysis |
|
||||||
|
| **Prettier** | Consistent code formatting |
|
||||||
|
| **Changesets** | Versioning and release management |
|
||||||
|
| **GitHub Actions** | Continuous Integration |
|
||||||
|
|
||||||
|
The technology stack is considered part of the project's architecture and may only be changed through a new Architecture Decision Record.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
|
||||||
|
Each technology has been selected because it directly supports one or more architectural principles.
|
||||||
|
|
||||||
|
### StencilJS
|
||||||
|
|
||||||
|
StencilJS enables the development of standards-based Web Components.
|
||||||
|
|
||||||
|
This aligns with the project's goal of remaining framework agnostic while allowing framework-specific wrappers to be generated automatically during the build process.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Storybook
|
||||||
|
|
||||||
|
Storybook provides an isolated environment for component development.
|
||||||
|
|
||||||
|
It supports rapid development, interactive examples, accessibility validation, and visual review of chart components.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Starlight
|
||||||
|
|
||||||
|
Starlight serves as the central documentation platform.
|
||||||
|
|
||||||
|
It separates architectural documentation from component documentation and supports long-term maintainability of the project's knowledge base.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### TypeScript
|
||||||
|
|
||||||
|
TypeScript enables strong compile-time validation.
|
||||||
|
|
||||||
|
It improves the developer experience by detecting integration errors early and providing comprehensive IDE support.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### pnpm
|
||||||
|
|
||||||
|
pnpm Workspaces enable a modular repository structure while maintaining a single source of truth for dependencies and tooling.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Jest
|
||||||
|
|
||||||
|
Jest provides fast unit testing for business logic, utility functions, configuration handling, validation, and other non-browser-specific functionality.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Playwright
|
||||||
|
|
||||||
|
Playwright validates component behavior inside real browsers.
|
||||||
|
|
||||||
|
It is used to verify keyboard interaction, focus management, SVG rendering, and other browser-dependent accessibility features.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### axe-core
|
||||||
|
|
||||||
|
axe-core automatically validates accessibility requirements and complements manual accessibility reviews.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### ESLint and Prettier
|
||||||
|
|
||||||
|
Both tools ensure consistent coding standards across the project and reduce friction during code reviews.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Changesets
|
||||||
|
|
||||||
|
Changesets manages package versioning and release notes while keeping release decisions under maintainer control.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### GitHub Actions
|
||||||
|
|
||||||
|
GitHub Actions automates testing, validation, and release workflows to ensure consistent software quality.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
### Positive
|
||||||
|
|
||||||
|
* Technology stack directly supports architectural principles.
|
||||||
|
* Strong accessibility support throughout development.
|
||||||
|
* Framework-independent component model.
|
||||||
|
* Excellent developer experience.
|
||||||
|
* Consistent documentation workflow.
|
||||||
|
* High maintainability.
|
||||||
|
* Modern testing strategy.
|
||||||
|
* Simplified contributor onboarding.
|
||||||
|
* Automated quality assurance.
|
||||||
|
* Scalable project foundation.
|
||||||
|
|
||||||
|
### Negative
|
||||||
|
|
||||||
|
* Initial project setup is more complex.
|
||||||
|
* Contributors must become familiar with multiple development tools.
|
||||||
|
* Toolchain maintenance requires periodic updates.
|
||||||
|
* CI configuration is more comprehensive than for smaller projects.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related TOGAF Phases
|
||||||
|
|
||||||
|
* Architecture Vision (Phase A)
|
||||||
|
* Information Systems Architecture (Phase C)
|
||||||
|
* Technology Architecture (Phase D)
|
||||||
|
* Opportunities & Solutions (Phase E)
|
||||||
|
* Migration Planning (Phase F)
|
||||||
|
* Implementation Governance (Phase G)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
* LUNA Charts Architecture Wiki
|
||||||
|
* ADR-0001: Repository Structure
|
||||||
|
* ADR-0003: Web Components as Public API
|
||||||
|
* StencilJS Documentation
|
||||||
|
* Storybook Documentation
|
||||||
|
* Starlight Documentation
|
||||||
|
* Playwright Documentation
|
||||||
|
* Jest Documentation
|
||||||
|
* pnpm Documentation
|
||||||
@@ -0,0 +1,110 @@
|
|||||||
|
# ADR-0003: Web Components as Public API
|
||||||
|
|
||||||
|
* **Status:** Accepted
|
||||||
|
* **Date:** 2026-07-12
|
||||||
|
* **Decision Makers:** LUNA Charts Maintainers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
LUNA Charts is intended to be an open-source charting library that can be integrated into applications regardless of the frontend framework used.
|
||||||
|
|
||||||
|
A primary architectural objective defined during the Architecture Vision and Technology Architecture phases is **framework agnosticism**. Consumers should be able to use LUNA Charts in React, Angular, Vue, Svelte, or plain HTML applications without requiring framework-specific implementations of the chart components.
|
||||||
|
|
||||||
|
The public API therefore had to be based on a stable and widely adopted web standard rather than a framework-specific component model.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision Drivers
|
||||||
|
|
||||||
|
The following factors influenced this decision:
|
||||||
|
|
||||||
|
* Framework Agnosticism
|
||||||
|
* Standards Compliance
|
||||||
|
* Long-Term Maintainability
|
||||||
|
* Accessibility
|
||||||
|
* Developer Experience
|
||||||
|
* Component Reusability
|
||||||
|
* Open Web Platform
|
||||||
|
* Future Compatibility
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Considered Alternatives
|
||||||
|
|
||||||
|
| Alternative | Description |
|
||||||
|
| -------------------------------------- | ----------------------------------------------------------------- |
|
||||||
|
| React Components | Components implemented exclusively for React. |
|
||||||
|
| Vue Components | Components implemented exclusively for Vue. |
|
||||||
|
| Angular Components | Components implemented exclusively for Angular. |
|
||||||
|
| Separate implementations per framework | Independent implementations for each supported framework. |
|
||||||
|
| **Web Components** | Standards-based custom elements implemented using Web Components. |
|
||||||
|
|
||||||
|
Framework-specific implementations were rejected because they increase maintenance effort, duplicate functionality, and couple the architecture to individual frontend ecosystems.
|
||||||
|
|
||||||
|
Maintaining multiple implementations would also increase the likelihood of inconsistent behavior across frameworks.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
LUNA Charts exposes its public API exclusively through **Web Components**.
|
||||||
|
|
||||||
|
The project uses **StencilJS** to implement these components according to the Web Components standard.
|
||||||
|
|
||||||
|
Framework integrations (e.g., React, Angular, Vue) are generated automatically during the build process and are considered **integration adapters**, not independent implementations.
|
||||||
|
|
||||||
|
The architecture therefore consists of a single component model with multiple consumption options.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
|
||||||
|
Web Components are an open web standard supported by all modern browsers.
|
||||||
|
|
||||||
|
By building directly upon this standard, LUNA Charts remains independent of any frontend framework while still supporting popular ecosystems through automatically generated wrappers.
|
||||||
|
|
||||||
|
This approach minimizes duplicated implementation effort and guarantees consistent functionality across all supported platforms.
|
||||||
|
|
||||||
|
Using a single implementation also simplifies testing, documentation, maintenance, and accessibility validation.
|
||||||
|
|
||||||
|
Framework wrappers remain lightweight integration layers and do not introduce architectural differences.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
### Positive
|
||||||
|
|
||||||
|
* Framework-independent public API.
|
||||||
|
* Single implementation for all supported platforms.
|
||||||
|
* Reduced maintenance effort.
|
||||||
|
* Consistent behavior across frameworks.
|
||||||
|
* Simplified testing and documentation.
|
||||||
|
* Better long-term stability.
|
||||||
|
* Supports future frontend frameworks without redesigning the library.
|
||||||
|
|
||||||
|
### Negative
|
||||||
|
|
||||||
|
* Developers unfamiliar with Web Components may require additional documentation.
|
||||||
|
* Framework wrappers depend on the capabilities provided by StencilJS.
|
||||||
|
* Some framework-specific features cannot be exposed without breaking framework independence.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related TOGAF Phases
|
||||||
|
|
||||||
|
* Architecture Vision (Phase A)
|
||||||
|
* Information Systems Architecture (Phase C)
|
||||||
|
* Technology Architecture (Phase D)
|
||||||
|
* Opportunities & Solutions (Phase E)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
* LUNA Charts Architecture Wiki
|
||||||
|
* ADR-0002: Technology Stack
|
||||||
|
* StencilJS Documentation
|
||||||
|
* Web Components Specification
|
||||||
@@ -0,0 +1,129 @@
|
|||||||
|
# ADR-0004: SVG as Rendering Technology
|
||||||
|
|
||||||
|
* **Status:** Accepted
|
||||||
|
* **Date:** 2026-07-12
|
||||||
|
* **Decision Makers:** LUNA Charts Maintainers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
One of the primary goals of LUNA Charts is to provide accessible chart components that support modern accessibility standards and assist developers in creating WCAG-compliant data visualizations.
|
||||||
|
|
||||||
|
Charts are graphical user interfaces that contain meaningful information. Depending on the chart type, individual graphical elements such as bars, points, labels, legends, and axes may need to be discoverable by assistive technologies, focusable using the keyboard, or interactable by users.
|
||||||
|
|
||||||
|
The rendering technology therefore has a direct impact on accessibility, developer experience, testing capabilities, maintainability, and future extensibility.
|
||||||
|
|
||||||
|
A rendering technology had to be selected that supports these architectural goals while remaining compatible with modern browsers and Web Components.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision Drivers
|
||||||
|
|
||||||
|
The following factors influenced this decision:
|
||||||
|
|
||||||
|
* Accessibility
|
||||||
|
* WCAG Compliance
|
||||||
|
* Semantic Structure
|
||||||
|
* Keyboard Navigation
|
||||||
|
* Focus Management
|
||||||
|
* Screen Reader Support
|
||||||
|
* Developer Experience
|
||||||
|
* Maintainability
|
||||||
|
* Browser Compatibility
|
||||||
|
* Long-Term Evolution
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Considered Alternatives
|
||||||
|
|
||||||
|
| Alternative | Description |
|
||||||
|
| ---------------- | --------------------------------------------------------- |
|
||||||
|
| HTML Elements | Represent charts using standard HTML elements. |
|
||||||
|
| Canvas | Render graphics using the HTML Canvas API. |
|
||||||
|
| Hybrid Rendering | Combine Canvas and SVG depending on the chart type. |
|
||||||
|
| **SVG** | Render all chart graphics using Scalable Vector Graphics. |
|
||||||
|
|
||||||
|
HTML was rejected because it is not designed to represent complex graphical visualizations.
|
||||||
|
|
||||||
|
Canvas was rejected because graphical objects are rendered as pixels rather than DOM elements. This makes individual chart elements difficult to expose to assistive technologies and increases implementation complexity for keyboard interaction and accessibility.
|
||||||
|
|
||||||
|
Hybrid rendering was rejected because it would introduce two rendering models, increasing architectural complexity, testing effort, and maintenance costs.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
All chart visualizations within LUNA Charts are rendered using **Scalable Vector Graphics (SVG)**.
|
||||||
|
|
||||||
|
Each visual element (e.g., bars, lines, points, labels, legends, and axes) is represented as an individual SVG element within the DOM.
|
||||||
|
|
||||||
|
Accessibility information, keyboard navigation, focus management, and interaction are implemented directly on these SVG elements.
|
||||||
|
|
||||||
|
Canvas is not used as a rendering technology for chart components.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
|
||||||
|
SVG integrates directly into the browser's Document Object Model (DOM), allowing every graphical element to be individually identified, styled, focused, and enriched with accessibility information.
|
||||||
|
|
||||||
|
This capability aligns with the project's goal of supporting accessible chart implementations by design.
|
||||||
|
|
||||||
|
Using SVG enables the library to:
|
||||||
|
|
||||||
|
* associate semantic information with graphical elements,
|
||||||
|
* support keyboard navigation,
|
||||||
|
* expose meaningful structures to assistive technologies,
|
||||||
|
* apply standard web accessibility techniques,
|
||||||
|
* simplify automated accessibility testing,
|
||||||
|
* integrate naturally with Web Components.
|
||||||
|
|
||||||
|
SVG also provides excellent scalability across different display resolutions without requiring additional rendering logic.
|
||||||
|
|
||||||
|
Although Canvas may provide better rendering performance for extremely large datasets, accessibility and maintainability are considered higher architectural priorities for LUNA Charts.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
### Positive
|
||||||
|
|
||||||
|
* Native DOM representation of graphical elements.
|
||||||
|
* Improved accessibility support.
|
||||||
|
* Better compatibility with assistive technologies.
|
||||||
|
* Simplified keyboard navigation.
|
||||||
|
* Simplified focus management.
|
||||||
|
* Easier automated accessibility testing.
|
||||||
|
* Resolution-independent rendering.
|
||||||
|
* Consistent styling using CSS.
|
||||||
|
* Better integration with Web Components.
|
||||||
|
* Simplified debugging using browser developer tools.
|
||||||
|
|
||||||
|
### Negative
|
||||||
|
|
||||||
|
* Rendering performance may decrease for extremely large datasets.
|
||||||
|
* SVG documents become larger as chart complexity increases.
|
||||||
|
* Very large visualizations may require optimization techniques such as virtualization or data aggregation.
|
||||||
|
|
||||||
|
These trade-offs are considered acceptable because accessibility and maintainability have higher architectural priority than maximum rendering performance.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related TOGAF Phases
|
||||||
|
|
||||||
|
* Architecture Vision (Phase A)
|
||||||
|
* Business Architecture (Phase B)
|
||||||
|
* Information Systems Architecture (Phase C)
|
||||||
|
* Technology Architecture (Phase D)
|
||||||
|
* Opportunities & Solutions (Phase E)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
* LUNA Charts Architecture Wiki
|
||||||
|
* ADR-0002: Technology Stack
|
||||||
|
* ADR-0003: Web Components as Public API
|
||||||
|
* Scalable Vector Graphics (SVG) Specification
|
||||||
|
* Web Content Accessibility Guidelines (WCAG)
|
||||||
@@ -0,0 +1,139 @@
|
|||||||
|
# ADR-000500: Accessibility as a Cross-Cutting Concern
|
||||||
|
|
||||||
|
* **Status:** Accepted
|
||||||
|
* **Date:** 2026-07-12
|
||||||
|
* **Decision Makers:** LUNA Charts Maintainers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
Accessibility is the primary quality attribute of LUNA Charts.
|
||||||
|
|
||||||
|
The project's objective is not only to render charts but also to support developers in creating accessible data visualizations that align with the Web Content Accessibility Guidelines (WCAG).
|
||||||
|
|
||||||
|
During the architectural design process, accessibility was initially considered as a separate subsystem responsible for validating and enforcing accessibility requirements.
|
||||||
|
|
||||||
|
Further analysis revealed that accessibility affects nearly every architectural layer of the system.
|
||||||
|
|
||||||
|
Rendering, component APIs, configuration, validation, interaction, keyboard navigation, documentation, and testing all contribute to the accessibility of the final chart.
|
||||||
|
|
||||||
|
As a result, accessibility cannot be implemented as an isolated engine without introducing architectural inconsistencies.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision Drivers
|
||||||
|
|
||||||
|
The following factors influenced this decision:
|
||||||
|
|
||||||
|
* Accessibility by Design
|
||||||
|
* WCAG Compliance
|
||||||
|
* Separation of Concerns
|
||||||
|
* Maintainability
|
||||||
|
* Consistency
|
||||||
|
* Developer Experience
|
||||||
|
* Long-Term Evolution
|
||||||
|
* Testability
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Considered Alternatives
|
||||||
|
|
||||||
|
| Alternative | Description |
|
||||||
|
| ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
|
||||||
|
| Dedicated Accessibility Engine | A centralized subsystem responsible for accessibility validation and enforcement. |
|
||||||
|
| Accessibility Utilities | A collection of reusable accessibility helper functions. |
|
||||||
|
| **Cross-Cutting Concern** | Accessibility is integrated into every architectural layer where accessibility-related decisions are made. |
|
||||||
|
|
||||||
|
A dedicated accessibility engine was rejected because accessibility cannot be guaranteed after a chart has already been designed or rendered.
|
||||||
|
|
||||||
|
Accessibility decisions must be made continuously throughout the rendering process and component lifecycle.
|
||||||
|
|
||||||
|
Accessibility utilities remain part of the implementation but do not represent the architectural model.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
Accessibility is treated as a **cross-cutting concern** throughout the entire architecture of LUNA Charts.
|
||||||
|
|
||||||
|
Accessibility responsibilities are distributed across multiple architectural modules rather than centralized in a single subsystem.
|
||||||
|
|
||||||
|
Examples include:
|
||||||
|
|
||||||
|
* Public component APIs
|
||||||
|
* TypeScript type definitions
|
||||||
|
* Validation
|
||||||
|
* Rendering
|
||||||
|
* SVG generation
|
||||||
|
* Keyboard interaction
|
||||||
|
* Focus management
|
||||||
|
* Documentation
|
||||||
|
* Automated testing
|
||||||
|
|
||||||
|
Each architectural component is responsible for implementing the accessibility requirements relevant to its own responsibility.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
|
||||||
|
Accessibility is not a feature that can be added after rendering has completed.
|
||||||
|
|
||||||
|
Instead, accessibility emerges from many architectural decisions working together.
|
||||||
|
|
||||||
|
Examples include:
|
||||||
|
|
||||||
|
* selecting SVG instead of Canvas,
|
||||||
|
* designing semantic component APIs,
|
||||||
|
* exposing accessible keyboard interaction,
|
||||||
|
* generating meaningful DOM structures,
|
||||||
|
* providing strongly typed configuration,
|
||||||
|
* validating accessibility-related configuration,
|
||||||
|
* documenting accessibility behavior,
|
||||||
|
* verifying accessibility through automated testing.
|
||||||
|
|
||||||
|
Treating accessibility as a cross-cutting concern ensures that accessibility remains an architectural responsibility rather than an isolated implementation detail.
|
||||||
|
|
||||||
|
This approach also aligns with established software architecture principles, where quality attributes such as security, logging, and observability are commonly treated as cross-cutting concerns.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
### Positive
|
||||||
|
|
||||||
|
* Accessibility is considered throughout the entire development process.
|
||||||
|
* Architectural responsibilities remain clearly separated.
|
||||||
|
* Accessibility becomes part of every feature rather than an optional extension.
|
||||||
|
* Better support for WCAG-compliant chart implementations.
|
||||||
|
* Simplified long-term maintenance.
|
||||||
|
* Consistent accessibility behavior across all chart types.
|
||||||
|
* Accessibility can be validated at multiple architectural levels.
|
||||||
|
|
||||||
|
### Negative
|
||||||
|
|
||||||
|
* Accessibility responsibilities are distributed across multiple modules.
|
||||||
|
* Contributors must understand accessibility requirements beyond their immediate implementation.
|
||||||
|
* Architectural reviews must continuously consider accessibility implications.
|
||||||
|
|
||||||
|
These trade-offs are acceptable because accessibility represents the primary quality objective of LUNA Charts.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related TOGAF Phases
|
||||||
|
|
||||||
|
* Architecture Vision (Phase A)
|
||||||
|
* Business Architecture (Phase B)
|
||||||
|
* Information Systems Architecture (Phase C)
|
||||||
|
* Technology Architecture (Phase D)
|
||||||
|
* Implementation Governance (Phase G)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
* LUNA Charts Architecture Wiki
|
||||||
|
* ADR-000300: Web Components as Public API
|
||||||
|
* ADR-000400: SVG as Rendering Technology
|
||||||
|
* Web Content Accessibility Guidelines (WCAG)
|
||||||
|
* WAI-ARIA Authoring Practices Guide
|
||||||
@@ -0,0 +1,190 @@
|
|||||||
|
# Architecture Decision Records (ADRs)
|
||||||
|
|
||||||
|
Architecture Wiki: [https://wiki.byting-pandas.ninja/en/Projects/LUNA-Charts/Introduction]
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This directory contains the **Architecture Decision Records (ADRs)** for the LUNA Charts project.
|
||||||
|
|
||||||
|
An Architecture Decision Record documents a significant architectural decision, the context in which it was made, the chosen solution, and its consequences.
|
||||||
|
|
||||||
|
The goal is to preserve the reasoning behind architectural decisions so that future contributors and maintainers understand **why** a decision was made—not only **what** was implemented.
|
||||||
|
|
||||||
|
ADRs complement the Architecture Development Method (ADM) documentation and serve as the primary record of architectural decisions throughout the project's lifecycle.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture Documentation
|
||||||
|
|
||||||
|
The complete software architecture of LUNA Charts is documented in the official Architecture Wiki.
|
||||||
|
|
||||||
|
The wiki follows the **TOGAF Architecture Development Method (ADM)** and describes the project from the initial vision through implementation governance and long-term architecture evolution.
|
||||||
|
|
||||||
|
### Architecture Wiki
|
||||||
|
|
||||||
|
* Architecture Vision (Phase A)
|
||||||
|
* Business Architecture (Phase B)
|
||||||
|
* Information Systems Architecture (Phase C)
|
||||||
|
* Technology Architecture (Phase D)
|
||||||
|
* Opportunities & Solutions (Phase E)
|
||||||
|
* Migration Planning (Phase F)
|
||||||
|
* Implementation Governance (Phase G)
|
||||||
|
* Architecture Change Management (Phase H)
|
||||||
|
|
||||||
|
The ADRs contained in this directory should always be read together with the Architecture Wiki.
|
||||||
|
|
||||||
|
The wiki describes the architecture as a whole, whereas ADRs explain the reasoning behind individual architectural decisions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Relationship to the Architecture Documentation
|
||||||
|
|
||||||
|
| Architecture Wiki | Architecture Decision Records |
|
||||||
|
| -------------------------------------------- | --------------------------------------------------- |
|
||||||
|
| Describes the complete software architecture | Documents individual architectural decisions |
|
||||||
|
| Defines the overall system structure | Explains why a specific solution was selected |
|
||||||
|
| Organized according to TOGAF ADM phases | Organized chronologically by architectural decision |
|
||||||
|
| Updated when the architecture evolves | Added whenever a significant decision is made |
|
||||||
|
|
||||||
|
ADRs do **not** replace the Architecture Wiki.
|
||||||
|
|
||||||
|
Likewise, the Architecture Wiki should not duplicate ADRs.
|
||||||
|
|
||||||
|
Instead, both artifacts complement each other.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## When to Create an ADR
|
||||||
|
|
||||||
|
An ADR should be created whenever a decision has a significant impact on the architecture of the project.
|
||||||
|
|
||||||
|
Typical examples include:
|
||||||
|
|
||||||
|
* Selecting a new technology
|
||||||
|
* Introducing or replacing an architectural pattern
|
||||||
|
* Changing the public API
|
||||||
|
* Introducing a new rendering strategy
|
||||||
|
* Changing accessibility principles
|
||||||
|
* Modifying the repository structure
|
||||||
|
* Changing release or governance processes
|
||||||
|
|
||||||
|
Small implementation details, bug fixes, refactorings, or coding style decisions do **not** require an ADR.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ADR Lifecycle
|
||||||
|
|
||||||
|
Every ADR has one of the following statuses:
|
||||||
|
|
||||||
|
| Status | Description |
|
||||||
|
| ---------- | ------------------------------------------------------- |
|
||||||
|
| Proposed | The decision is under discussion. |
|
||||||
|
| Accepted | The decision has been approved and adopted. |
|
||||||
|
| Deprecated | The decision is no longer recommended but still exists. |
|
||||||
|
| Superseded | The decision has been replaced by another ADR. |
|
||||||
|
| Discarded | The proposal was rejected. |
|
||||||
|
|
||||||
|
Only **Accepted** ADRs represent the current architecture.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ADR Structure
|
||||||
|
|
||||||
|
Each ADR follows the same structure.
|
||||||
|
|
||||||
|
```text
|
||||||
|
Title
|
||||||
|
|
||||||
|
Status
|
||||||
|
|
||||||
|
Context
|
||||||
|
|
||||||
|
Decision Drivers
|
||||||
|
|
||||||
|
Considered Alternatives
|
||||||
|
|
||||||
|
Decision
|
||||||
|
|
||||||
|
Rationale
|
||||||
|
|
||||||
|
Consequences
|
||||||
|
Positive
|
||||||
|
Negative
|
||||||
|
|
||||||
|
Related TOGAF Phases
|
||||||
|
|
||||||
|
References
|
||||||
|
```
|
||||||
|
|
||||||
|
This structure ensures that every ADR answers the following questions:
|
||||||
|
|
||||||
|
* **What** decision was made?
|
||||||
|
* **Why** was the decision necessary?
|
||||||
|
* **When** was it made?
|
||||||
|
* **Who** approved the decision?
|
||||||
|
* **What** are the expected consequences?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Naming Convention
|
||||||
|
|
||||||
|
ADRs use sequential numbering.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
```text
|
||||||
|
0001-repository-structure.md
|
||||||
|
0002-technology-stack.md
|
||||||
|
0003-svg-rendering.md
|
||||||
|
```
|
||||||
|
|
||||||
|
The number is never reused.
|
||||||
|
|
||||||
|
If an ADR becomes obsolete, its status changes instead of deleting the document.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision Process
|
||||||
|
|
||||||
|
Architectural decisions follow the governance model defined in **Implementation Governance (Phase G)**.
|
||||||
|
|
||||||
|
```text
|
||||||
|
Proposal
|
||||||
|
↓
|
||||||
|
Architecture Discussion
|
||||||
|
↓
|
||||||
|
Architecture Review
|
||||||
|
↓
|
||||||
|
Maintainer Decision
|
||||||
|
↓
|
||||||
|
ADR Update
|
||||||
|
↓
|
||||||
|
Implementation
|
||||||
|
```
|
||||||
|
|
||||||
|
Community members are encouraged to participate in discussions.
|
||||||
|
|
||||||
|
Final architectural decisions are made by the project maintainers.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Relationship to Source Code
|
||||||
|
|
||||||
|
Source code is expected to reflect accepted ADRs.
|
||||||
|
|
||||||
|
If an implementation no longer follows an accepted ADR, one of the following actions should occur:
|
||||||
|
|
||||||
|
* Update the implementation to match the ADR.
|
||||||
|
* Replace the ADR with a new architectural decision.
|
||||||
|
* Deprecate or supersede the ADR.
|
||||||
|
|
||||||
|
Architectural changes should always be documented before or together with the implementation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
* TOGAF Architecture Development Method (ADM)
|
||||||
|
* LUNA Charts Architecture Wiki
|
||||||
|
* LUNA Charts Implementation Governance (Phase G)
|
||||||
|
* LUNA Charts Architecture Change Management (Phase H)
|
||||||
@@ -0,0 +1,117 @@
|
|||||||
|
# ADR-XXXX: Title
|
||||||
|
|
||||||
|
* **Status:** Proposed
|
||||||
|
* **Date:** YYYY-MM-DD
|
||||||
|
* **Decision Makers:** LUNA Charts Maintainers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
Describe the background that led to this decision.
|
||||||
|
|
||||||
|
Questions that should be answered:
|
||||||
|
|
||||||
|
* What problem needs to be solved?
|
||||||
|
* Which architectural constraints exist?
|
||||||
|
* Which project goals influence the decision?
|
||||||
|
* Which stakeholders are affected?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision Drivers
|
||||||
|
|
||||||
|
List the primary factors that influenced the decision.
|
||||||
|
|
||||||
|
Typical examples:
|
||||||
|
|
||||||
|
* Accessibility
|
||||||
|
* Performance
|
||||||
|
* Developer Experience
|
||||||
|
* Maintainability
|
||||||
|
* Framework Agnosticism
|
||||||
|
* Type Safety
|
||||||
|
* Simplicity
|
||||||
|
* Scalability
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Considered Alternatives
|
||||||
|
|
||||||
|
Document all relevant alternatives.
|
||||||
|
|
||||||
|
| Alternative | Description |
|
||||||
|
| ----------- | ----------- |
|
||||||
|
| Option A | Description |
|
||||||
|
| Option B | Description |
|
||||||
|
| Option C | Description |
|
||||||
|
|
||||||
|
Briefly explain why the alternatives were not selected.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
Describe the selected solution.
|
||||||
|
|
||||||
|
This section should clearly answer:
|
||||||
|
|
||||||
|
> What has been decided?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
|
||||||
|
Explain why the selected solution best satisfies the decision drivers.
|
||||||
|
|
||||||
|
This section should justify the decision from an architectural perspective.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
### Positive
|
||||||
|
|
||||||
|
Describe the expected benefits.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* Improved maintainability
|
||||||
|
* Better accessibility
|
||||||
|
* Easier onboarding
|
||||||
|
* Reduced complexity
|
||||||
|
|
||||||
|
### Negative
|
||||||
|
|
||||||
|
Describe possible drawbacks.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* Increased implementation effort
|
||||||
|
* Additional maintenance
|
||||||
|
* Performance trade-offs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related TOGAF Phases
|
||||||
|
|
||||||
|
List all architecture phases that influenced this decision.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* Architecture Vision (Phase A)
|
||||||
|
* Technology Architecture (Phase D)
|
||||||
|
* Implementation Governance (Phase G)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
Provide references to related documentation.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* Architecture Wiki
|
||||||
|
* Other ADRs
|
||||||
|
* External standards
|
||||||
|
* Specifications
|
||||||
@@ -0,0 +1,11 @@
|
|||||||
|
---
|
||||||
|
title: Example Guide
|
||||||
|
description: A guide in my new Starlight docs site.
|
||||||
|
---
|
||||||
|
|
||||||
|
Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
|
||||||
|
Writing a good guide requires thinking about what your users are trying to do.
|
||||||
|
|
||||||
|
## Further reading
|
||||||
|
|
||||||
|
- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework
|
||||||
@@ -0,0 +1,40 @@
|
|||||||
|
---
|
||||||
|
title: Welcome to Starlight
|
||||||
|
description: Get started building your docs site with Starlight.
|
||||||
|
template: splash # Remove or comment out this line to display the site sidebar on this page.
|
||||||
|
hero:
|
||||||
|
tagline: Congrats on setting up a new Starlight project!
|
||||||
|
image:
|
||||||
|
file: ../../assets/houston.webp
|
||||||
|
actions:
|
||||||
|
- text: Example Guide
|
||||||
|
link: /guides/example/
|
||||||
|
icon: right-arrow
|
||||||
|
- text: Read the Starlight docs
|
||||||
|
link: https://starlight.astro.build
|
||||||
|
icon: external
|
||||||
|
variant: minimal
|
||||||
|
---
|
||||||
|
|
||||||
|
import { Card, CardGrid } from '@astrojs/starlight/components';
|
||||||
|
|
||||||
|
## Next steps
|
||||||
|
|
||||||
|
<CardGrid stagger>
|
||||||
|
<Card title="Update content" icon="pencil">
|
||||||
|
Edit `src/content/docs/index.mdx` to see this page change.
|
||||||
|
</Card>
|
||||||
|
<Card title="Change page layout" icon="document">
|
||||||
|
Delete `template: splash` in `src/content/docs/index.mdx` to display a
|
||||||
|
sidebar on this page.
|
||||||
|
</Card>
|
||||||
|
<Card title="Add new content" icon="add-document">
|
||||||
|
Add Markdown or MDX files to `src/content/docs` to create new pages.
|
||||||
|
</Card>
|
||||||
|
<Card title="Configure your site" icon="setting">
|
||||||
|
Edit your `sidebar` and other config in `astro.config.mjs`.
|
||||||
|
</Card>
|
||||||
|
<Card title="Read the docs" icon="open-book">
|
||||||
|
Learn more in [the Starlight Docs](https://starlight.astro.build/).
|
||||||
|
</Card>
|
||||||
|
</CardGrid>
|
||||||
@@ -0,0 +1,11 @@
|
|||||||
|
---
|
||||||
|
title: Example Reference
|
||||||
|
description: A reference page in my new Starlight docs site.
|
||||||
|
---
|
||||||
|
|
||||||
|
Reference pages are ideal for outlining how things work in terse and clear terms.
|
||||||
|
Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting.
|
||||||
|
|
||||||
|
## Further reading
|
||||||
|
|
||||||
|
- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework
|
||||||
@@ -0,0 +1,5 @@
|
|||||||
|
{
|
||||||
|
"extends": "astro/tsconfigs/strict",
|
||||||
|
"include": [".astro/types.d.ts", "**/*"],
|
||||||
|
"exclude": ["dist"]
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user