Ninosaurier
2b5ce8a233
Corrects two Architecture Decision Records that had drifted from the actual implementation during this sprint. - ADR-0002 (Technology Stack): unit testing now uses Vitest instead of Jest; Playwright's role is clarified as the browser provider used by Vitest's browser mode rather than a standalone test runner. - ADR-0001 (Repository Structure): repository diagram updated to remove the unused apps/ directory, correct the docs/ path to match the actual Starlight content location, and add the previously missing adm/ folder. Both ADRs now include a Change Log section documenting what changed and why, per the Architecture Change Management process (ADM Phase H).
164 lines
5.8 KiB
Plaintext
164 lines
5.8 KiB
Plaintext
---
|
||
title: "ADR-0001000: Repository Structure"
|
||
description: "Decision to use a pnpm-based monorepo structure for LUNA Charts."
|
||
---
|
||
|
||
* **Status:** Accepted
|
||
* **Date:** 2026-07-12
|
||
* **Last Updated:** 2026-07-17
|
||
* **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/
|
||
│ └── .storybook/
|
||
│
|
||
├── docs/
|
||
│ └── src/content/docs/architecture/
|
||
│ ├── adr/
|
||
│ └── adm/
|
||
│
|
||
├── examples/
|
||
│
|
||
├── .changeset/
|
||
│
|
||
└── .github/
|
||
```
|
||
|
||
Storybook is not maintained as a separate app but lives directly inside the `packages/luna-charts` package, alongside the component source code it documents.
|
||
The `docs/` workspace is not nested under an `apps/` directory; it is a top-level workspace built with Starlight, with architecture documentation (ADR and ADM) organized under `docs/src/content/docs/architecture/`.
|
||
|
||
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
|
||
|
||
---
|
||
|
||
## Change Log
|
||
|
||
### 2026-07-17 – Repository structure diagram updated (removal of `apps/`)
|
||
|
||
**Reason**
|
||
|
||
The originally planned `apps/` workspace (containing `apps/storybook` and `apps/docs`) was never adopted in this form during implementation. Storybook was instead kept inside `packages/luna-charts` alongside the component source it documents, and the documentation workspace (`docs/`) was placed directly at the repository root rather than nested under `apps/`. The repository structure diagram in this ADR no longer matched the actual repository layout, while the Getting Started documentation (`project-structure.mdx`) already reflected the current structure.
|
||
|
||
**Changes**
|
||
|
||
* Removed the `apps/` directory (and its `storybook/` and `docs/` subentries) from the structure diagram
|
||
* Corrected the `docs/` path to reflect the actual Starlight content location (`docs/src/content/docs/architecture/`)
|
||
* Added the `adm/` folder to the diagram, alongside `adr/`, since Architecture Development Method documentation is stored there as well
|
||
* Added `.changeset/` to the diagram, as it is a workspace-level configuration directory used for release management
|
||
* Added a note clarifying that Storybook is maintained as part of the `packages/luna-charts` package rather than as a separate app
|
||
|
||
**Impact**
|
||
|
||
The overall decision (pnpm-based monorepo with logical workspace separation) is unaffected. Only the illustrative directory layout was corrected to match the implemented structure. No other ADRs are impacted by this change. |