ADR System

🏛️ Architectural Decision Record System with automatic file monitoring

Features

✅ Real-time file monitoring with intelligent change detection
✅ Interactive CLI prompts for capturing architectural decisions
✅ Automatic ADR generation in Markdown format
✅ Sequential numbering (0001, 0002, etc.)
✅ Editor-based input for detailed descriptions
✅ Related file tracking
✅ Status management (proposed, accepted, deprecated, superseded)
✅ Tags and metadata support

Installation

npm install

Usage

Start the ADR System

# Watch current directory
npm start

# Watch specific directory
npm run watch

# Development mode with hot reload
npm run dev

How It Works

1. The system monitors your project files for changes
2. When a file is modified, added, or deleted, you'll be prompted
3. Answer a few questions about the architectural decision
4. ADR is automatically generated in the ./adrs folder

ADR Format

Each ADR includes:

• Title: Brief description of the decision
• Status: proposed | accepted | deprecated | superseded
• Context: The problem or issue being addressed
• Decision: What was decided and why
• Consequences: Positive and negative outcomes
• Related Files: Files affected by this decision
• Metadata: Date, authors, tags

Example ADR Output

# 0001. Use TypeScript for ADR System

**Date:** 2026-02-02  
**Status:** accepted  
**Authors:** Development Team
**Tags:** `typescript`, `tooling`

---

## Context

We needed a reliable file monitoring system...

---

## Decision

We decided to use TypeScript with Node.js...

---

## Consequences

### Positive
- Type safety
- Better IDE support

### Negative
- Additional build step required

---

Configuration

Customize the watch folder and ADR output location:

npm start <watch-folder> <adr-folder>

Example:

npm start ./src ./docs/adrs

Building

npm run build

This compiles TypeScript to JavaScript in the dist folder.

Technologies Used

• TypeScript: Type-safe development
• Chokidar: File system watching
• Inquirer: Interactive CLI prompts
• Chalk: Terminal styling
• Node.js: Runtime environment

Why TypeScript over Python?

• ✅ Superior file system watching APIs
• ✅ Async/await native support
• ✅ Better cross-platform compatibility
• ✅ Fast I/O operations
• ✅ Excellent VS Code integration
• ✅ Strong typing for reliability

License

MIT