---
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.