@boundless-oss/atlas/src/modules/documentation/MIGRATION.md

Atlas - MCP Server for comprehensive startup project management

# Documentation Module Migration to 12-Factor MCP

## Overview

The documentation module has been migrated from file-based storage to SQLite using the 12-Factor MCP pattern. This migration provides better data consistency, querying capabilities, and follows the standardized architecture patterns.

## Changes Made

### 1. New Files Created

- **`tools.ts`** - Implements all documentation tools using the standardized tool framework
  - `generate_readme` - Generate README.md files
  - `generate_claude_config` - Generate CLAUDE.md configuration
  - `create_documentation` - Create various documentation types
  - `list_documents` - List and filter documents
  - `update_document` - Update existing documents
  - `search_documents` - Search documents by content

- **`index-new.ts`** - New module entry point that exports the tool registration

- **`legacy-wrapper.ts`** - Provides backward compatibility for existing tools
  - Maps old tool names to new implementations
  - Transforms legacy arguments to new format
  - Formats output to match legacy expectations

### 2. Database Schema

Documents are now stored in the `documents` table with the following structure:
```sql
CREATE TABLE IF NOT EXISTS documents (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    type TEXT NOT NULL DEFAULT 'markdown',
    path TEXT,
    tags TEXT DEFAULT '[]',
    status TEXT NOT NULL DEFAULT 'draft',
    author TEXT,
    version INTEGER DEFAULT 1,
    created_at INTEGER NOT NULL DEFAULT (unixepoch()),
    updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
    FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
);
```

### 3. Server Configuration

The server.ts file has been updated to:
1. Try loading the new SQLite-based module first
2. Fall back to the legacy file-based module if the new one fails
3. Register the legacy wrapper for backward compatibility

### 4. Migration Support

The existing migration.ts already includes support for migrating documentation data from JSON files to SQLite through the `migrateDocumentationData` method.

## Benefits

1. **Structured Data** - Documents are stored with proper metadata and relationships
2. **Better Querying** - SQL-based searching and filtering capabilities
3. **Version Control** - Built-in versioning for document updates
4. **Multi-Project Support** - Documents are properly scoped by project ID
5. **Stateless Operation** - Tools follow the 12-Factor principle of stateless execution

## Backward Compatibility

The legacy wrapper ensures that existing integrations continue to work:
- Old tool names are mapped to new implementations
- Arguments are transformed to match new schemas
- Output is formatted to match legacy expectations

## Testing

A new test file `documentation-tools.test.ts` has been created to verify:
- All tools are properly registered
- Schema validation is in place
- Read-only tools are marked correctly

## Usage

The module can be used in two ways:

1. **New Pattern** (Recommended):
```typescript
const { setupDocumentation } = await import('./modules/documentation/index-new.js');
const registration = await setupDocumentation();
```

2. **Legacy Pattern** (For compatibility):
```typescript
const { setupDocumentationTools } = await import('./modules/documentation/index.js');
const module = await setupDocumentationTools(server, configManager);
```

## Next Steps

1. Monitor for any issues during the transition period
2. Eventually deprecate and remove the legacy file-based implementation
3. Update all consumers to use the new tool names and patterns