@roadmap-generator/core

Dynamic roadmap generation engine - A reusable SDK for creating structured, domain-aware product roadmaps programmatically.

A production-ready npm package that generates deterministic product roadmaps for SaaS, Mobile, Data, E-commerce, and Internal Tools. Used by the Roadmap Generator backend and available as a standalone SDK for direct Node.js/TypeScript integration.

Test Coverage: 64/64 tests passing ✅ | Status: Production Ready 🚀

Features

✅ Deterministic & Reproducible - Same input always produces identical roadmaps (validated with tests)
✅ Domain-Aware Generation - Built-in templates for SaaS, Mobile, Data, E-commerce, Internal Tools
✅ Flexible Phase System - Define custom phases (v1.2.0+), use predefined templates, or create plugins
✅ Flexible Outputs - Markdown, Timeline, and JSON formats
✅ Type-Safe - Full TypeScript support with Zod runtime validation
✅ Zero Dependencies - Minimal footprint (only Zod for schema validation)
✅ Configurable - Customize horizons (weeks/months/quarters) and detail levels (high/medium/detailed)
✅ Well-Tested - 100% test coverage across core logic, domain packs, and renderers

Installation

npm install @roadmap-generator/core

Quick Start

import { generateRoadmap, renderRoadmapMarkdown } from '@roadmap-generator/core';

const roadmap = generateRoadmap({
  projectContext: {
    projectName: 'My SaaS App',
    domain: 'saas',
    targetAudience: 'Enterprise teams',
    constraints: ['6-month timeline'],
  },
  roadmapSpec: {
    horizon: 'months',
    levelOfDetail: 'medium',
    outputFormat: 'json',
  },
});

console.log(roadmap);

// Render to Markdown
const markdown = renderRoadmapMarkdown(roadmap);
console.log(markdown);

Common Use Cases

1. Generate a Product Roadmap for Stakeholders

import { generateRoadmap, renderRoadmapMarkdown } from '@roadmap-generator/core';

const request = {
  projectContext: {
    projectName: 'Analytics Dashboard',
    domain: 'saas',
    targetAudience: 'Mid-market businesses',
    constraints: ['$500k budget', '12-month timeline'],
  },
  roadmapSpec: {
    horizon: 'quarters',  // Higher level: quarterly milestones
    levelOfDetail: 'high',  // More phases to communicate
  },
};

const roadmap = generateRoadmap(request);
const markdown = renderRoadmapMarkdown(roadmap);

// Share with stakeholders
console.log(markdown);

2. Generate Multiple Roadmap Variants

// Compare roadmap views for planning
const highlevelRoadmap = generateRoadmap({
  projectContext: { projectName: 'Product X', domain: 'mobile' },
  roadmapSpec: { horizon: 'quarters', levelOfDetail: 'medium' },
});

const detailedRoadmap = generateRoadmap({
  projectContext: { projectName: 'Product X', domain: 'mobile' },
  roadmapSpec: { horizon: 'weeks', levelOfDetail: 'detailed' },
});

console.log('Quarterly Overview:', highlevelRoadmap);
console.log('Detailed Weekly Plan:', detailedRoadmap);

3. Export Roadmap in Multiple Formats

import {
  generateRoadmap,
  renderRoadmapMarkdown,
  renderRoadmapTimeline,
} from '@roadmap-generator/core';

const roadmap = generateRoadmap({
  projectContext: { projectName: 'My App', domain: 'data' },
  roadmapSpec: { horizon: 'months', levelOfDetail: 'medium' },
});

// Export as Markdown for documentation
const markdown = renderRoadmapMarkdown(roadmap);
fs.writeFileSync('roadmap.md', markdown);

// Export as Timeline for presentations
const timeline = renderRoadmapTimeline(roadmap);
fs.writeFileSync('roadmap-timeline.txt', timeline);

// Export as JSON for APIs
const json = JSON.stringify(roadmap, null, 2);
fs.writeFileSync('roadmap.json', json);

4. Use in Express API Endpoint

import express from 'express';
import { generateRoadmap } from '@roadmap-generator/core';

const app = express();

app.post('/api/roadmaps/generate', (req, res) => {
  try {
    const roadmap = generateRoadmap(req.body);
    res.json(roadmap);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

app.listen(3000);

Types

import type {
  GenerateRoadmapRequest,
  GenerateRoadmapResponse,
  RoadmapNode,
  ProjectContext,
  RoadmapSpec,
} from '@roadmap-generator/core';

API

generateRoadmap(input: GenerateRoadmapRequest): GenerateRoadmapResponse

Generates a structured roadmap based on the input request.

Input:

{
  projectContext: {
    projectName: string;           // Required: e.g., "My Product"
    domain?: string;               // e.g., "saas", "mobile", "data", "ecommerce"
    targetAudience?: string;       // e.g., "Enterprise teams"
    description?: string;          // Project description
    constraints?: string[];        // e.g., ["6-month timeline", "limited budget"]
  },
  roadmapSpec: {
    horizon?: "weeks" | "months" | "quarters";  // Default: "months"
    levelOfDetail?: "high" | "medium" | "detailed";  // Default: "medium"
    outputFormat?: string;         // e.g., "json", "markdown", "timeline"
  }
}

Output:

{
  roadmapId: string;               // Deterministic hash-based ID
  nodes: RoadmapNode[];            // Phases/milestones
  warnings: string[];              // Validation warnings
  assumptions: string[];           // Key assumptions
  metadata: {
    version: string;
    generatedAt: string;           // ISO 8601 timestamp
  }
}

renderRoadmapMarkdown(roadmap: GenerateRoadmapResponse): string

Renders roadmap as Markdown.

renderRoadmapTimeline(roadmap: GenerateRoadmapResponse): string

Renders roadmap as a plain-text timeline.

resolveDomainPack(domain?: string): DomainPack

Resolves the appropriate domain pack for dynamic phase injection.

createRoadmapId(input: GenerateRoadmapRequest): string

Creates a deterministic roadmap ID based on the request.

Domain Packs

Each domain pack injects domain-specific phases and assumptions into your roadmap.

| Domain | Supported Values | Key Phases | Best For | |--------|-----------------|-----------|----------| | SaaS | saas, software as a service, b2b software | Validation, Onboarding, Retention | Web/cloud applications | | Mobile | mobile, ios, android, app | Platform Setup, Store Readiness, Distribution | iOS/Android applications | | Data | data, analytics, bi, pipeline | Data Modeling, Pipeline Design, Quality | Data warehouses, ETL tools | | E-commerce | ecommerce, commerce, retail | Catalog, Checkout, Fulfillment | Online stores, marketplaces | | Internal | internal, ops, operations | Process Mapping, Adoption, Training | Internal tools, workflows | | Default | Any other value | Generic phases only | When domain is unknown |

Example: SaaS Domain

const saasRoadmap = generateRoadmap({
  projectContext: {
    projectName: 'Collaboration Platform',
    domain: 'saas',  // Triggers SaaS domain pack
    targetAudience: 'Enterprise',
    constraints: ['Must support SSO', 'GDPR compliance'],
  },
  roadmapSpec: {
    horizon: 'quarters',
    levelOfDetail: 'high',
  },
});

// Roadmap will include:
// - Validation phase (ICP, pricing)
// - Onboarding phase (activation, first-run experience)
// - Custom warnings about SaaS requirements
// - Assumptions about retention and user activation

Example: Mobile Domain

const mobileRoadmap = generateRoadmap({
  projectContext: {
    projectName: 'Fitness Tracker App',
    domain: 'mobile',  // Triggers Mobile domain pack
  },
  roadmapSpec: {
    horizon: 'weeks',  // More frequent for mobile development
    levelOfDetail: 'detailed',
  },
});

// Roadmap will include:
// - Platform Setup phase (architecture, state management)
// - Store Readiness phase (app store submission)
// - Mobile-specific assumptions

Example: Using with Backend

import { generateRoadmap } from '@roadmap-generator/core';

// In a REST endpoint:
app.post('/roadmaps', (req, res) => {
  const roadmap = generateRoadmap(req.body);
  const stored = await repository.createVersion({ roadmap, request: req.body });
  res.json(stored);
});

Using with Your Own Database

This SDK is database-agnostic - it generates roadmaps without storing them. To persist roadmaps:

Option A: Use Standalone (No Database)

// Just generate and render - no persistence needed
const roadmap = generateRoadmap(request);
const markdown = renderRoadmapMarkdown(roadmap);
// Send to user directly

Option B: Connect to Your Database

import { generateRoadmap } from '@roadmap-generator/core';

app.post('/roadmaps', async (req, res) => {
  // Generate roadmap using this SDK
  const roadmap = generateRoadmap(req.body);
  
  // Store in YOUR database (MongoDB, PostgreSQL, MySQL, DynamoDB, etc.)
  const stored = await myDatabase.create({
    id: roadmap.roadmapId,
    request: req.body,
    roadmap: roadmap,
    createdAt: new Date(),
  });
  
  res.json(stored);
});

Backend reference implementation: See the Roadmap Generator Backend for a complete example using PostgreSQL with versioning, sharing, and AI insights.

Database Flexibility

• ✅ Works with any database (PostgreSQL, MySQL, MongoDB, etc.)
• ✅ Choose your own schema design
• ✅ Add custom fields (user_id, team_id, tags, etc.)
• ✅ Implement your own version control strategy
• ✅ Add features like sharing, collaboration, audit trails

✨ Flexible Phase System (v1.2.0+)

The flexible phase system removes rigidity by offering three complementary approaches:

A. Custom Phases - Maximum Control

Define phases exactly as needed for your project:

import { generateRoadmap } from '@roadmap-generator/core';

const roadmap = generateRoadmap({
  projectContext: { projectName: 'My Project' },
  roadmapSpec: { horizon: 'months' },
  customPhases: [
    {
      id: 'research',
      title: 'Research & Validation',
      duration: 2,
      unit: 'weeks',
      priority: 'high',
      dependencies: [],
    },
    // ... more phases
  ],
});

C. Predefined Templates - Proven Patterns

Use 4 battle-tested templates: agile, waterfall, mvp-first, lean

const roadmap = generateRoadmap({
  projectContext: { projectName: 'Startup MVP' },
  roadmapSpec: { horizon: 'months' },
  template: 'mvp-first', // Quick to market
});

D. Phase Plugins - Reusable Collections

Create or use plugins for domain-specific phases:

import { registerBuiltinPlugins, generateRoadmap } from '@roadmap-generator/core';

registerBuiltinPlugins();

const roadmap = generateRoadmap({
  projectContext: { projectName: 'SaaS App' },
  roadmapSpec: { horizon: 'months' },
  phasePlugins: ['saas-launch', 'ecommerce-launch'], // Combine plugins
});

Built-in Plugins:

• saas-launch - Validation → Pricing → Onboarding → Retention
• healthcare-compliance - HIPAA → Clinical → Regulatory → Testing
• ecommerce-launch - Catalog → Payments → Fulfillment → Marketing
• mobile-launch - Architecture → Core Features → Store Prep → Beta

Learn More: See FLEXIBILITY.md for comprehensive guide and examples.

Documentation

• FLEXIBILITY.md - Complete guide for custom phases, templates, and plugins
• CHANGELOG.md - Version history and release notes
• examples/flexible-phases-examples.ts - Real-world usage patterns

Development

# Install dependencies
npm install

# Type check
npm run check

# Build to dist/
npm run build

# Run tests (64 tests, 100% pass rate)
npm test

# Clean build artifacts
npm run clean

# Format code
npm run format

Testing

This SDK includes comprehensive test coverage:

# Run all tests
npm test

# Test output:
# ✔ SDK - Core Generation (9 tests)
# ✔ SDK - Domain Packs (9 tests)
# ✔ SDK - Renderers (11 tests)
# ✔ SDK - Rules (14 tests)
# ✔ SDK - Schemas (16 tests)
# Total: 64/64 passing

Project Structure

packages/core/
├── src/
│   ├── core/
│   │   ├── roadmap-engine.ts      # Main generation algorithm
│   │   ├── domain-packs.ts        # Domain customization
│   │   ├── rule-set.ts            # Warnings & assumptions
│   │   └── renderers.ts           # Output formatting
│   ├── schemas/                   # Zod validation schemas
│   └── index.ts                   # Public API exports
├── test/
│   ├── core.test.ts               # Core engine tests
│   ├── domain-packs.test.ts       # Domain pack tests
│   ├── renderers.test.ts          # Renderer tests
│   ├── rules.test.ts              # Rules tests
│   └── schemas.test.ts            # Schema validation tests
└── package.json                   # npm configuration

Performance

• Generation Time: < 10ms for typical roadmaps
• Bundle Size: ~150KB (unminified)
• Memory: Minimal (single-pass algorithm)
• Dependencies: Only Zod (~5KB)

API Reference

All types are fully documented in TypeScript. Here are the main types:

// Request
interface GenerateRoadmapRequest {
  projectContext: {
    projectName: string;                    // Required
    domain?: string;                        // Optional: saas|mobile|data|ecommerce|internal
    targetAudience?: string;                // Optional
    description?: string;                   // Optional
    constraints?: string[];                 // Optional: e.g., ["6-month", "budget"]
  };
  roadmapSpec: {
    horizon?: 'weeks' | 'months' | 'quarters';  // Default: months
    levelOfDetail?: 'high' | 'medium' | 'detailed';  // Default: medium
    outputFormat?: string;                  // Optional: used by renderers
  };
}

// Response
interface GenerateRoadmapResponse {
  roadmapId: string;                        // Deterministic ID
  nodes: RoadmapNode[];                     // Phases/milestones
  warnings: string[];                       // Validation warnings
  assumptions: string[];                    // Key assumptions
  metadata: {
    version: string;
    generatedAt: string;                    // ISO 8601 timestamp
  };
}

// Node in roadmap
interface RoadmapNode {
  id: string;                               // Unique phase ID
  title: string;                            // Display name
  description: string;                      // Detailed description
  status: 'planned' | 'in-progress' | 'completed';
  dependsOn: string[];                      // Dependencies on other phases
}

Browser Usage

This SDK is Node.js only and uses server-side features. For browser usage, use the REST API:

// Browser-safe approach
const response = await fetch('/api/roadmaps/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(roadmapRequest),
});

const roadmap = await response.json();

Troubleshooting

Issue: Schema validation fails

Solution: Ensure input matches the expected types:

import { generateRoadmapRequestSchema } from '@roadmap-generator/core';

// Validate before calling
try {
  const validated = generateRoadmapRequestSchema.parse(input);
  const roadmap = generateRoadmap(validated);
} catch (error) {
  console.error('Invalid input:', error.errors);
}

Issue: Roadmap IDs don't match

Solution: generateRoadmap and createRoadmapId should always produce the same ID for identical input. If they differ, check that the input is truly identical (including constraints array order).

Contributing

Found a bug or want to add a feature? Please open an issue or PR on GitHub.

Support

• 📧 Email: [email protected]
• 📚 Full Documentation
• 🐛 Issue Tracker

License

MIT - See LICENSE file for details

Made with ❤️ by the Roadmap Generator team