✨ Your new, shiny Nx workspace is ready ✨.

Learn more about this workspace setup and its capabilities or run npx nx graph to visually explore what was created. Now, let's get you up to speed!

• Run Tasks
• Add New Projects
• Research-Wiki Integration
• Set Up CI
• Install Nx Console
• Useful Links

To run the dev server for your app, use:

npx nx serve wiki-graph

To create a production bundle:

npx nx build wiki-graph

To see all available targets to run for a project, run:

npx nx show project wiki-graph

These targets are either inferred automatically or defined in the project.json or package.json files.

More about running tasks in the docs »

While you could add new projects to your workspace manually, you might want to leverage Nx plugins and their code generation feature.

Use the plugin's generator to create new projects.

To generate a new application, use:

npx nx g @nx/angular:app demo

To generate a new library, use:

npx nx g @nx/angular:lib mylib

You can use npx nx list to get a list of installed plugins. Then, run npx nx list <plugin-name> to learn about more specific capabilities of a particular plugin. Alternatively, install Nx Console to browse plugins and generators in your IDE.

Learn more about Nx plugins » | Browse the plugin registry »

This workspace includes an integrated research and knowledge management system that automatically captures technical decisions and research findings into a structured wiki.

The research-wiki integration automates the flow from library research to documented decisions:

Research → Finalize → ADR → Wiki Ingestion → Searchable Knowledge Base

When you complete a research session and create an Architecture Decision Record (ADR), the system automatically:

1. Copies the ADR to the wiki ingestion pipeline
2. Generates structured wiki pages with metadata
3. Creates cross-references to related concepts and entities
4. Maintains bidirectional links between research sessions and wiki pages
5. Makes decisions searchable and discoverable

The wiki system is organized as a collection of Nx libraries following clean architecture principles with four distinct layers:

• Domain Layer (@wiki/domain-*): Core business entities and validation rules with zero external dependencies
• Application Layer (@wiki/application-*): Use case orchestration services coordinating domain operations through port interfaces
• Infrastructure Layer (@wiki/infrastructure-*): Technical implementations of file system, markdown, and frontmatter adapters
• Presentation Layer (@wiki/core): Public API facade providing unified access to all wiki functionality

See libs/wiki/ARCHITECTURE.md for complete architectural documentation.

.kiro/
├── research/                          # Research sessions
│   └── [session-id]/                  # Individual research session
│       ├── decision.adr.md            # Architecture Decision Record (preserved)
│       ├── comparison-report.md       # Library comparison analysis
│       ├── final-report.md            # Research conclusions
│       └── prototypes/                # Code prototypes for evaluation
│
└── specs/                             # Feature specifications
    └── [feature-name]/
        ├── requirements.md
        ├── design.md
        └── tasks.md

raw/
├── research-decisions/                # ADRs ready for wiki ingestion
│   └── decision.adr.md                # Copied from research sessions
│
├── articles/                          # External articles and papers
├── code-snippets/                     # Code examples
├── notes/                             # General notes
└── papers/                            # Academic papers

wiki/
├── sources/                           # Source_Summary pages (generated from ADRs)
│   └── [decision-name].md             # Structured decision documentation
│
├── entities/                          # Entity_Page entries (libraries, tools)
│   └── [library-name].md              # Library information and relationships
│
├── concepts/                          # Concept_Page entries (patterns, techniques)
│   └── [concept-name].md              # Conceptual knowledge
│
└── guides/                            # How-to guides and workflows
    └── adr-ingestion.md               # ADR ingestion guide

libs/wiki/                             # Wiki system Nx libraries (clean architecture)
├── domain-models/                     # Core domain entities (WikiPage, RawSource, etc.)
├── domain-naming/                     # Naming convention validation and generation
├── domain-validation/                 # Domain-level validation rules
├── application-ports/                 # Port interface definitions
├── application-generators/            # Page generation use cases
├── application-cross-reference/       # Cross-reference detection and linking
├── application-index-manager/         # Index management use cases
├── application-activity-log/          # Activity logging use cases
├── application-query/                 # Search and query use cases
├── application-maintenance/           # Maintenance and health check use cases
├── application-workflow/              # High-level workflow orchestration
├── application-adr/                   # ADR-specific use cases
├── infrastructure-filesystem/         # File system adapter implementation
├── infrastructure-markdown/           # Markdown parsing and formatting adapter
├── infrastructure-frontmatter/        # Frontmatter processing adapter
└── core/                              # Public API facade

Start a new research session to explore library options:

# Create research session directory
mkdir -p .kiro/research/session-2024-01-15-state-management
cd .kiro/research/session-2024-01-15-state-management

# Create research artifacts
touch comparison-report.md
touch final-report.md
mkdir prototypes

Document your research findings:

• Compare library features and trade-offs
• Build prototypes to evaluate options
• Analyze performance, complexity, and maintainability
• Document insights in comparison and final reports

When you've made a decision, create decision.adr.md:

---
title: "Choose NgRx for State Management"
date: 2024-01-15
status: accepted
context: "Need centralized state management for large Angular application"
deciders: ["team-lead", "senior-dev"]
tags: ["angular", "state-management", "ngrx"]
sessionId: "session-2024-01-15-state-management"
---

# Choose NgRx for State Management

## Context and Problem Statement

We need a robust state management solution for our Angular application with
strong type safety, excellent debugging tools, and good community support.

## Decision Drivers

- Type safety and compile-time checks
- DevTools support for debugging
- Community support and ecosystem
- Learning curve for team
- Performance characteristics

## Considered Options

1. NgRx
2. Akita
3. NGXS

## Comparison Matrix

### Feature Comparison

| Feature | NgRx | Akita | NGXS | Winner |
|---------|------|-------|------|--------|
| Type Safety | Excellent | Good | Good | NgRx |
| DevTools | Excellent | Good | Good | NgRx |
| Learning Curve | Steep | Moderate | Easy | NGXS |
| Community | Large | Medium | Medium | NgRx |
| Performance | Excellent | Excellent | Good | NgRx/Akita |

## Decision Outcome

Chosen option: **NgRx**

### Rationale

NgRx provides the strongest type safety and best DevTools support, which are
critical for our large-scale application. While the learning curve is steeper,
the long-term benefits of type safety and debugging capabilities outweigh the
initial investment.

### Consequences

- Positive: Strong type safety, excellent debugging, large community
- Negative: Steeper learning curve, more boilerplate code
- Neutral: Well-established patterns, extensive documentation

## Research Links

- [Comparison Report](./comparison-report.md)
- [Final Report](./final-report.md)
- [NgRx Prototype](./prototypes/ngrx/)
- [Akita Prototype](./prototypes/akita/)

Ingest the ADR into the wiki system:

import { runADRIngestionWorkflow } from '@wiki/application-adr';

// Ingest ADR from research session
const result = await runADRIngestionWorkflow({
  sessionDirectory: '.kiro/research/session-2024-01-15-state-management'
});

console.log('ADR ingestion complete!');
console.log('Generated pages:');
result.generatedPages.forEach(page => {
  console.log(`  - ${page.type}: ${page.path}`);
});

The workflow automatically:

1. Copies ADR: From .kiro/research/[session-id]/decision.adr.md to raw/research-decisions/
2. Parses Metadata: Extracts frontmatter, decision drivers, comparison matrices, and library names
3. Generates Wiki Pages:
   • wiki/sources/choose-ngrx-for-state-management.md (Source_Summary)
   • wiki/entities/ngrx.md (Entity_Page)
   • wiki/entities/akita.md (Entity_Page)
   • wiki/entities/ngxs.md (Entity_Page)
4. Creates Cross-References: Links to existing Entity and Concept pages
5. Updates Indexes: Adds pages to wiki index with tags
6. Records Activity: Logs ingestion event and creates git commit

Search for research decisions in the wiki:

import { queryWiki } from '@wiki/application-query';

// Find all research decisions
const decisions = await queryWiki({
  tags: ['research', 'adr']
});

// Find decisions about specific library
const ngrxDecisions = await queryWiki({
  entityName: 'NgRx',
  tags: ['adr']
});

// Find recent state management decisions
const stateDecisions = await queryWiki({
  tags: ['state-management', 'adr'],
  sortBy: 'date',
  order: 'desc'
});

The integration maintains bidirectional links between research sessions and wiki pages:

From Wiki to Research:

Each Source_Summary page includes a "Session Reference" section linking back to the original research session:

## Session Reference

This decision originated from research session: 
[session-2024-01-15-state-management](../.kiro/research/session-2024-01-15-state-management/)

### Research Artifacts
- [Comparison Report](../.kiro/research/session-2024-01-15-state-management/comparison-report.md)
- [Final Report](../.kiro/research/session-2024-01-15-state-management/final-report.md)
- [Prototype: NgRx](../.kiro/research/session-2024-01-15-state-management/prototypes/ngrx/)
- [Prototype: Akita](../.kiro/research/session-2024-01-15-state-management/prototypes/akita/)

From Research to Wiki:

ADRs can reference existing wiki pages, and the system automatically detects and links these references during ingestion.

Here's a complete example of the research-to-wiki workflow:

import { runADRIngestionWorkflow } from '@wiki/application-adr';
import { queryWiki } from '@wiki/application-query';

// 1. Ingest ADR from completed research session
const ingestionResult = await runADRIngestionWorkflow({
  sessionDirectory: '.kiro/research/session-2024-01-15-state-management'
});

console.log('Generated pages:');
ingestionResult.generatedPages.forEach(page => {
  console.log(`  ${page.type}: ${page.path}`);
});

// 2. Query for the new decision
const newDecision = await queryWiki({
  tags: ['adr'],
  filter: (page) => page.title.includes('NgRx')
});

console.log('\nDecision details:');
console.log(`  Title: ${newDecision[0].title}`);
console.log(`  Date: ${newDecision[0].metadata.date}`);
console.log(`  Status: ${newDecision[0].metadata.status}`);
console.log(`  Session: ${newDecision[0].metadata.sessionId}`);

// 3. Find related decisions
const relatedDecisions = await queryWiki({
  tags: ['state-management', 'adr']
});

console.log(`\nFound ${relatedDecisions.length} related decisions`);

• Automatic ADR Copy: ADRs are automatically copied from research sessions to wiki ingestion pipeline
• Metadata Extraction: Parses frontmatter, decision drivers, comparison matrices, and library names
• Structured Wiki Pages: Generates Source_Summary and Entity_Page entries with consistent formatting
• Cross-Referencing: Automatically detects and links related entities and concepts
• Bidirectional Links: Maintains links from wiki to research sessions and vice versa
• Searchable: All decisions are indexed and searchable by tags, libraries, and dates
• Version Control: All wiki changes are committed to git with descriptive messages
• Activity Logging: Records all ingestion events for audit and tracking

For detailed information about the research-wiki integration:

• Research Workflow: See .kiro/steering/library-research.md for complete research workflow documentation
• ADR Ingestion Guide: See wiki/guides/adr-ingestion.md for step-by-step ingestion instructions
• Architecture Guide: See libs/wiki/ARCHITECTURE.md for architectural documentation and library relationships
• Wiki Schema: See WIKI_SCHEMA.md for wiki page structure and conventions

The wiki system includes maintenance tools to keep content up-to-date:

import { runMaintenanceWorkflow } from '@wiki/application-maintenance';

// Run maintenance checks
const report = await runMaintenanceWorkflow();

// Check for issues
console.log('Broken session references:', report.brokenSessionReferences);
console.log('Duplicate entities:', report.duplicateEntities);
console.log('Superseded decisions:', report.supersededDecisions);

The maintenance workflow validates:

• Session reference links point to existing research sessions
• No duplicate Entity_Page entries for the same library
• Superseded ADRs are properly marked and linked
• Cross-reference links are valid and up-to-date

To connect to Nx Cloud, run the following command:

npx nx connect

Connecting to Nx Cloud ensures a fast and scalable CI pipeline. It includes features such as:

• Remote caching
• Task distribution across multiple machines
• Automated e2e test splitting
• Task flakiness detection and rerunning

Use the following command to configure a CI workflow for your workspace:

npx nx g ci-workflow

Learn more about Nx on CI

Nx Console is an editor extension that enriches your developer experience. It lets you run tasks, generate code, and improves code autocompletion in your IDE. It is available for VSCode and IntelliJ.

Install Nx Console »

Learn more:

• Learn more about this workspace setup
• Learn about Nx on CI
• Releasing Packages with Nx release
• What are Nx plugins?

And join the Nx community:

• Discord
• Follow us on X or LinkedIn
• Our Youtube channel
• Our blog