# Repository Knowledge Graph Design

## Goal

Build a first-pass knowledge graph for this component library by adding a minimal SDD layer and generating two deliverables: machine-readable JSON and a human-readable Mermaid diagram.

The graph focuses on static repository knowledge, not runtime behavior.

## Scope

This first version covers:

- source exports and component registration in `src/index.ts`
- component modules under `src/`
- shared utilities and types under `src/`
- documentation pages under `docs/`
- example routes and pages under `examples/`

This first version does not model backend APIs, databases, or business process flows.

## Proposed SDD Layout

- `.aspirecode/sdd/rules.md`
  - repository-wide coding and architecture rules
- `.aspirecode/sdd/feature_v1.0.0/spec.md`
  - graph scope, entities, relations, and source-of-truth rules
- `.aspirecode/sdd/feature_v1.0.0/data-model.md`
  - graph entity definitions and relation semantics
- `.aspirecode/sdd/feature_v1.0.0/api-contract.md`
  - input and output contract for graph generation
- `.aspirecode/sdd/feature_v1.0.0/task.yaml`
  - implementation task breakdown for graph generation

## Graph Output

The graph generator produces:

- `knowledge-graph.json`
- `knowledge-graph.mmd`

The JSON and Mermaid outputs must describe the same entity set and relation set.

## Component Architecture Diagram

The first-pass architecture diagram should present the component library in four layers so the repository structure is readable at a glance.

### Layering

- Public entry layer
  - `src/index.ts`
- Core capability layer
  - `ProTable`
  - `ProForm`
  - `ProDescriptions`
  - `CollapseContainer`
  - `ProTableForm`
- Reuse and support layer
  - `useProTable`
  - `useForm`
  - `useDescription`
  - `useProTableForm`
  - `useComponentSetting`
  - shared utilities and type modules
- Knowledge and demo layer
  - `docs/*.md`
  - `examples/router.ts`
  - `examples/pages/**`

### Mermaid Draft

```mermaid
graph TD
  entry[src/index.ts]

  subgraph CoreComponents
    protable[ProTable]
    proform[ProForm]
    prodesc[ProDescriptions]
    collapse[CollapseContainer]
    protableform[ProTableForm]
  end

  subgraph ComposablesAndSupport
    useptable[useProTable]
    useform[useForm]
    usedesc[useDescription]
    useptform[useProTableForm]
    setting[useComponentSetting]
    utils[utils and types]
  end

  subgraph DocsAndExamples
    docs[docs/*.md]
    router[examples/router.ts]
    demos[examples/pages/**]
  end

  entry --> protable
  entry --> proform
  entry --> prodesc
  entry --> collapse
  entry --> protableform

  protable --> useptable
  protable --> setting
  protable --> utils

  proform --> useform
  proform --> utils

  prodesc --> usedesc
  prodesc --> utils

  protableform --> useptform
  protableform --> utils

  docs --> protable
  docs --> proform
  docs --> prodesc
  docs --> collapse
  docs --> protableform

  router --> demos
  demos --> protable
  demos --> proform
  demos --> prodesc
  demos --> collapse
  demos --> protableform
```

This diagram is intentionally static. It shows ownership, export, and demonstration relationships, not runtime render trees.

## Core Entities

- `Component`
  - library components such as `ProTable`, `ProForm`, `ProDescriptions`, `CollapseContainer`, and `ProTableForm`
- `Composable`
  - reusable hooks such as `useProTable`, `useForm`, `useDescription`, and `useProTableForm`
- `Utility`
  - shared helpers such as `useComponentSetting` and formatting utilities
- `TypeExport`
  - exported types from `src/index.ts` and type modules
- `DocPage`
  - documentation pages under `docs/`
- `ExamplePage`
  - example views under `examples/pages/`
- `Route`
  - route records from `examples/router.ts`

## Core Relations

- `exports`
  - source modules export public components, hooks, or types
- `documents`
  - docs pages describe components or usage patterns
- `demonstrates`
  - example pages demonstrate component usage
- `depends_on`
  - one entity relies on another entity for behavior or reuse
- `registers`
  - `src/index.ts` registers components for global install
- `belongs_to_route_group`
  - routes and pages belong to the example app navigation structure

## Source Priority

1. `src/index.ts`
2. component source files under `src/`
3. `docs/*.md`
4. `examples/router.ts`
5. `examples/pages/**`

If a doc or example conflicts with source exports, source code wins.

## SDD Draft Rules

- keep the model static and repository-oriented
- avoid inventing runtime behavior that does not exist in the repository
- keep entity names aligned with exported names and documented names
- prefer explicit relations over inferred narrative links

## Acceptance Criteria

- a valid `.aspirecode/sdd/rules.md` exists
- the feature version folder exists with `spec.md`, `data-model.md`, `api-contract.md`, and `task.yaml`
- the graph generator can emit both JSON and Mermaid from the same source set
- the graph includes components, composables, utilities, docs, examples, and routes
- the Mermaid output includes a top-level component architecture diagram matching the repository layering
- the output is consistent with the repository structure currently present in `src/`, `docs/`, and `examples/`