Skip to content
/ specmorph-app Public

SpecMorph is a cutting edge web application that leverages AI to automatically transform Software Requirements Specification (SRS) documents into professional UML diagrams.

specmorph.vercel.app
1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

paradocx96/specmorph-app

BranchesTags

Repository files navigation

🎨 SpecMorph

AI-Powered SRS to UML Diagram Generator

Transform Software Requirements Specifications into UML diagrams automatically with AI

Features • Quick Start • Documentation • Demo • Contributing

Next.js TypeScript Tailwind CSS React Query Framer Motion License: MIT PRs Welcome

divider

📖 Table of Contents

🎯 About

SpecMorph is a cutting-edge web application that leverages AI to automatically transform Software Requirements Specification (SRS) documents into professional UML diagrams. Built with modern web technologies and featuring a stunning glassmorphism UI, SpecMorph streamlines the software design process by automating diagram generation.

🔍 Problem Statement

Creating UML diagrams from SRS documents is time-consuming and prone to human error. Software architects and developers spend countless hours manually:

  • Reading and analyzing SRS documents
  • Identifying entities, relationships, and use cases
  • Drawing UML diagrams manually
  • Maintaining consistency across multiple diagrams

💡 Solution

SpecMorph automates this entire workflow using AI-powered extraction and intelligent diagram generation, reducing what takes hours into minutes while maintaining accuracy and consistency.

✨ Key Features

🎨 Beautiful UI/UX

  • Glassmorphism Design - Modern frosted glass effects with backdrop blur
  • Animated Gradients - Dynamic liquid gradient background animations
  • Fully Responsive - Seamless experience across desktop, tablet, and mobile
  • Dark Theme - Eye-friendly dark mode with violet-indigo accents
  • Smooth Animations - Framer Motion powered micro-interactions

🚀 Core Functionality

  • 📄 Document Management - Upload, organize, and process multiple SRS PDF documents
  • 🧠 AI-Powered Extraction - Intelligent extraction of requirements, entities, and relationships
  • 📊 UML Diagram Generation - Automatic creation of Class, Sequence, and Use Case diagrams
  • 🔄 Workflow Automation - One-click complete pipeline from upload to diagrams
  • ⚡ Real-time Updates - Live progress tracking with polling
  • 💾 Smart Caching - TanStack Query for optimized data fetching

🛠️ Advanced Features

  • 🔍 Search & Filter - Find diagrams and documents quickly
  • 📥 Bulk Operations - Upload, delete, and manage multiple items at once
  • 🖼️ Interactive Preview - Full-screen diagram viewing with zoom
  • ⬇️ Export Options - Download diagrams in multiple formats
  • 📈 Dashboard Analytics - Overview of system stats and recent activity
  • 🎯 Type-Safe - Full TypeScript support for better DX

📸 Demo

🖼️ Click to view screenshots

Dashboard

Dashboard

Workflow Automation

Workflow

Diagram Gallery

Diagrams

Document Management

Documents

🛠️ Tech Stack

Frontend Framework

Styling & UI

State & Data Management

Developer Experience

⚡ Quick Start

# Clone the repository
git clone https://github.com/paradocx96/specmorph-app.git

# Navigate to project directory
cd specmorph-app

# Install dependencies
pnpm install

# Copy environment variables
cp .env.local.example .env.local

# Start development server
pnpm dev

Open http://localhost:3000 in your browser 🚀

📦 Installation

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js 18.x or higher (Download)
  • pnpm 8.x or higher (recommended) or npm 
    npm install -g pnpm
  • SpecMorph Backend API running on http://localhost:8000

Step-by-Step Installation

1️⃣ Clone the Repository

git clone https://github.com/paradocx96/specmorph-app.git
cd specmorph-app

2️⃣ Install Dependencies

Using pnpm (recommended):

pnpm install

Using npm:

npm install

Using yarn:

yarn install

3️⃣ Configure Environment Variables

Create a .env.local file:

cp .env.local.example .env.local

Edit the file and add your configuration:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000

# Debug mode (optional)
# NEXT_PUBLIC_DEBUG=true

4️⃣ Start Development Server

pnpm dev

The application will be available at http://localhost:3000

5️⃣ Verify Installation

  • ✅ Frontend accessible at http://localhost:3000
  • ✅ Backend API running at http://localhost:8000
  • ✅ API health check: http://localhost:8000/api/health

🔧 Environment Variables

Create a .env.local file in the root directory:

Variable Description Required Default
NEXT_PUBLIC_API_URL Backend API base URL ✅ Yes http://localhost:8000
NEXT_PUBLIC_DEBUG Enable debug mode ❌ No false

Example Configuration

# Development
NEXT_PUBLIC_API_URL=http://localhost:8000

# Production
NEXT_PUBLIC_API_URL=https://api.specmorph.com

📁 Project Structure

specmorph-app/
├── public/                             # Static assets
├── src/
│   ├── app/                            # Next.js App Router
│   │   ├── layout.tsx                  # Root layout
│   │   ├── page.tsx                    # Dashboard (Home)
│   │   ├── loading.tsx                 # Loading UI
│   │   ├── error.tsx                   # Error boundary
│   │   ├── not-found.tsx               # 404 page
│   │   ├── documents/                  # Document management page
│   │   │   └── page.tsx
│   │   ├── extraction/                 # AI extraction viewer
│   │   │   └── page.tsx
│   │   ├── diagrams/                   # Diagram gallery
│   │   │   └── page.tsx
│   │   └── workflow/                   # Automated workflow
│   │       └── page.tsx
│   │
│   ├── components/                     # React components
│   │   ├── ui/                         # Base UI primitives
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   ├── dialog.tsx
│   │   │   ├── input.tsx
│   │   │   ├── badge.tsx
│   │   │   ├── tabs.tsx
│   │   │   └── ...
│   │   ├── common/                     # Shared components
│   │   │   ├── loading-spinner.tsx
│   │   │   ├── error-display.tsx
│   │   │   ├── empty-state.tsx
│   │   │   ├── file-upload-zone.tsx
│   │   │   └── diagram-card.tsx
│   │   ├── layout/                     # Layout components
│   │   │   ├── sidebar.tsx
│   │   │   ├── header.tsx
│   │   │   └── navigation.tsx
│   │   ├── diagram/                    # Diagram-specific components
│   │   ├── document/                   # Document-specific components
│   │   └── workflow/                   # Workflow-specific components
│   │
│   ├── hooks/                          # Custom React hooks
│   │   ├── use-documents.ts
│   │   ├── use-diagrams.ts
│   │   ├── use-extraction.ts
│   │   ├── use-workflow.ts
│   │   └── index.ts
│   │
│   ├── services/                       # API service layer
│   │   ├── diagram.service.ts
│   │   ├── document.service.ts
│   │   ├── extraction.service.ts
│   │   └── workflow.service.ts
│   │
│   ├── store/                          # Zustand state management
│   │   └── index.ts
│   │
│   ├── types/                          # TypeScript type definitions
│   │   ├── api.ts
│   │   └── index.ts
│   │
│   ├── lib/                            # Configuration & utilities
│   │   ├── axios.ts                    # Axios instance
│   │   └── constants.ts                # API endpoints
│   │
│   ├── utils/                          # Utility functions
│   │   └── index.ts
│   │
│   └── assets/                         # Styles and static files
│       └── styles/
│           └── globals.css             # Global styles
│
├── .env.local.example                  # Environment variables template
├── .gitignore
├── next.config.ts                      # Next.js configuration
├── tailwind.config.ts                  # Tailwind CSS configuration
├── tsconfig.json                       # TypeScript configuration
├── package.json
└── README.md

📖 Usage Guide

1️⃣ Upload Documents

Navigate to Documents page:

  1. Click Upload button or drag & drop PDF files
  2. Supported formats: PDF
  3. Multiple files can be uploaded at once

2️⃣ Process Documents

After uploading:

  1. Click Process All to chunk documents
  2. Wait for processing to complete
  3. View processed chunks in Extraction page

3️⃣ Extract Data

Go to Extraction page:

  1. Click Extract to run AI extraction
  2. View extracted requirements, entities, and relationships
  3. Review structured data before diagram generation

4️⃣ Generate Diagrams

Navigate to Diagrams page:

  1. Click Generate Diagrams
  2. System creates:
    • Class Diagrams
    • Sequence Diagrams
    • Use Case Diagrams
  3. View, download, or delete diagrams

5️⃣ Automated Workflow (Recommended)

For complete automation, use Workflow page:

  1. Upload documents
  2. Click Start Workflow
  3. Monitor real-time progress
  4. Automatically get all diagrams

🎨 Design System

Colors

The design uses a dark theme with violet/indigo accent colors:

  • Background: slate-950 (#0a0a0f)
  • Primary: Violet-Indigo gradient
  • Success: Emerald
  • Warning: Amber
  • Error: Red

Components

All components feature glassmorphism effects:

  • Glass Card: Frosted glass effect with backdrop blur
  • Buttons: Gradient backgrounds with glow effects
  • Inputs: Glass-style with focus animations
  • Badges: Color-coded status indicators

Animations

  • Animated liquid gradient background
  • Smooth page transitions
  • Micro-interactions on hover/focus
  • Progress tracking animations

🔌 API Integration

The frontend connects to the SpecMorph Backend API using Axios with type-safe TypeScript interfaces.

API Configuration

Located in src/lib/axios.ts:

const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  timeout: 30000,
  headers: {
    'Content-Type': 'application/json',
  },
});

Endpoints

Feature Method Endpoint Description
Documents
List Documents GET /api/v1/documents Get all documents with pagination
Upload Document POST /api/v1/documents/upload Upload single PDF
Bulk Upload POST /api/v1/documents/bulk-upload Upload multiple PDFs
Delete Document DELETE /api/v1/documents/:id Delete by ID
Process Documents POST /api/v1/documents/process Create chunks
Extraction
Get Chunks GET /api/v1/extraction/chunks View text chunks
Extract Data POST /api/v1/extraction/extract Run AI extraction
Get Extraction GET /api/v1/extraction Get extraction results
Diagrams
List Diagrams GET /api/v1/diagrams/list Get all diagrams
Generate Diagrams GET /api/v1/diagrams/generate Create UML diagrams
Download Diagram GET /api/v1/diagrams/download/:filename Download file
Delete Diagram DELETE /api/v1/diagrams/:filename Delete diagram
Bulk Delete POST /api/v1/diagrams/bulk-delete Delete multiple
Workflow
Execute Workflow POST /api/v1/workflow/execute Start automation
Get Status GET /api/v1/workflow/status/:id Check progress
List Workflows GET /api/v1/workflow Get history
System
Health Check GET /api/health API status
Statistics GET /api/v1/stats System stats

Request/Response Types

All API calls use TypeScript interfaces defined in src/types/api.ts:

interface DiagramQueryParams {
  page?: number;
  limit?: number;
  search?: string;
  diagram_type?: 'class' | 'sequence' | 'usecase';
  sort_by?: string;
  sort_order?: 'asc' | 'desc';
}

interface DiagramsListResponse {
  data: DiagramInfo[];
  success: boolean;
  pagination: DocumentPagination;
  metadata: ResponseMetadata;
}

📱 Pages Overview

🏠 Dashboard (/)

  • System Stats - Documents, chunks, extractions count
  • API Health - Real-time backend status
  • Recent Activity - Latest documents and diagrams
  • Quick Actions - Fast access to common tasks
  • Storage Info - Disk usage statistics

📄 Documents (/documents)

  • Drag & Drop Upload - Intuitive file upload zone
  • Document List - Paginated table view
  • Search & Filter - Find documents quickly
  • Bulk Operations - Select multiple for deletion
  • Process All - Batch document processing
  • Status Indicators - Processed/unprocessed badges

🧠 Extraction (/extraction)

  • Text Chunks Viewer - Browse processed text
  • AI Extraction Results - Requirements, entities, relationships
  • Structured Data - UML entities with attributes/methods
  • Validation Status - Data quality indicators
  • Export Options - Download extraction data

📊 Diagrams (/diagrams)

  • Gallery View - Grid/list toggle
  • Type Filters - Class, Sequence, Use Case
  • Full-Screen Preview - Expandable diagram viewer
  • Download - Export diagrams
  • Bulk Delete - Multi-select operations
  • Generation - Create new diagrams from extraction

🔄 Workflow (/workflow)

  • Automated Pipeline - One-click complete process
  • Progress Tracking - Real-time step updates
  • Step Visualization - Visual progress indicators
  • Result Preview - Generated diagrams preview
  • Workflow History - Past executions log
  • Error Handling - Failure notifications and retry

🧪 Development

Available Scripts

# Development
pnpm dev          # Start development server (http://localhost:3000)
pnpm dev --turbo  # Start with Turbopack (faster)

# Building
pnpm build        # Create production build
pnpm start        # Start production server

# Code Quality
pnpm lint         # Run ESLint
pnpm type-check   # Run TypeScript compiler check

Development Workflow

  1. Create a feature branch

    git checkout -b feature/your-feature-name

  2. Make changes and test locally

    pnpm dev

  3. Check code quality

    pnpm lint
pnpm build

  4. Commit and push

    git add .
git commit -m "feat: add your feature"
git push origin feature/your-feature-name

Code Style Guidelines

  • TypeScript - Strict mode enabled
  • ESLint - Next.js recommended config
  • Prettier - Automatic code formatting (recommended)
  • Naming Conventions:
    • Components: PascalCase (DiagramCard.tsx)
    • Utilities: camelCase (buildQueryString())
    • Types: PascalCase (DiagramInfo)
    • Constants: UPPER_SNAKE_CASE (API_BASE_URL)

Project Conventions

  • Use React Server Components where possible
  • Implement error boundaries for all pages
  • Add loading states for async operations
  • Write type-safe API calls
  • Follow component composition pattern
  • Use custom hooks for reusable logic

🏗️ Building for Production

Local Production Build

# Build the application
pnpm build

# Start production server
pnpm start

The built application will be available at http://localhost:3000

Build Output

.next/
├── cache/              # Build cache
├── server/             # Server-side code
├── static/             # Static assets
└── standalone/         # Self-contained deployment

Performance Optimizations

  • ✅ Automatic code splitting
  • ✅ Image optimization with Next.js Image
  • ✅ TanStack Query caching
  • ✅ Tree shaking
  • ✅ Minification
  • ✅ Gzip compression

🚀 Deployment

Vercel (Recommended)

Deploy with Vercel

  1. Push code to GitHub
  2. Import project in Vercel
  3. Add environment variables
  4. Deploy

Docker Deployment

Dockerfile:

FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

# Install dependencies
COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Build application
RUN corepack enable pnpm && pnpm build

# Production image
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

CMD ["node", "server.js"]

Build and run:

# Build image
docker build -t specmorph-app .

# Run container
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=http://your-api-url:8000 \
  specmorph-app

Docker Compose

version: '3.8'

services:
  frontend:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=http://backend:8000
    depends_on:
      - backend

  backend:
    image: specmorph-api:latest
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/specmorph

Netlify

  1. Connect your GitHub repository
  2. Build settings:
    • Build command: pnpm build
    • Publish directory: .next
  3. Add environment variables
  4. Deploy

AWS / Azure / GCP

See Next.js Deployment Documentation for platform-specific guides.

🐛 Troubleshooting

Common Issues

Images not loading from backend

Problem: Diagrams showing broken image icons

Solution:

  1. Verify backend is running on correct port
  2. Check CORS configuration in backend
  3. Ensure next.config.ts has correct remotePatterns:
images: {
  remotePatterns: [
    {
      protocol: 'http',
      hostname: 'localhost',
      port: '8000',
      pathname: '/static/**',
    },
  ],
}
  1. Add unoptimized prop to <Image> components for development
API connection refused

Problem: Cannot connect to backend API

Solutions:

  • Verify backend is running: curl http://localhost:8000/api/health
  • Check .env.local has correct NEXT_PUBLIC_API_URL
  • Ensure no firewall blocking port 8000
  • Check browser console for CORS errors
Build errors with TypeScript

Problem: Type errors during build

Solutions:

# Clear cache
rm -rf .next node_modules
pnpm install

# Check types
pnpm type-check

# Update dependencies
pnpm update
Slow performance

Optimizations:

  • Enable TanStack Query caching
  • Use React Server Components
  • Implement pagination for large lists
  • Enable browser caching
  • Optimize images

Getting Help

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

How to Contribute

  1. Fork the repository

    git clone https://github.com/your-username/specmorph-app.git

  2. Create a feature branch

    git checkout -b feature/amazing-feature

  3. Make your changes

    • Write clean, documented code
    • Follow the code style guidelines
    • Add tests if applicable

  4. Test your changes

    pnpm dev
pnpm build
pnpm lint

  5. Commit using conventional commits

    git commit -m "feat: add amazing feature"

    Types: feat, fix, docs, style, refactor, test, chore

  6. Push to your fork

    git push origin feature/amazing-feature

  7. Open a Pull Request

    • Describe your changes clearly
    • Link related issues
    • Wait for review

Contribution Guidelines

  • 📝 Update documentation for new features
  • ✅ Ensure all tests pass
  • 🎨 Follow existing code style
  • 💬 Write meaningful commit messages
  • 🐛 Report bugs with detailed information
  • 💡 Discuss major changes in issues first

Code of Conduct

Be respectful, inclusive, and professional. See CODE_OF_CONDUCT.md for details.

🗺️ Roadmap

🚧 In Progress

  • Advanced diagram customization options
  • Real-time collaborative editing
  • Multiple theme support (light mode)

📋 Planned Features

  • Export diagrams to PNG/SVG/PDF formats
  • Diagram version history and comparison
  • Custom AI model configuration
  • Integration with popular project management tools
  • API rate limiting and authentication
  • Multi-language support (i18n)
  • Advanced search with filters
  • Diagram templates library
  • Mobile app (React Native)

💭 Future Ideas

  • Plugin system for extensibility
  • AI-powered diagram suggestions
  • Collaborative team workspaces
  • Integration with GitHub/GitLab
  • Automated testing for diagrams
  • Performance analytics dashboard

Want to contribute to any of these? Check out the Contributing section!

❓ FAQ

What file formats are supported for upload?

Currently, only PDF files are supported. The system extracts text from PDF documents for processing.

How accurate is the AI extraction?

Accuracy depends on:

  • Quality of the SRS document
  • Clarity of requirements
  • AI model used in the backend

Typical accuracy: 85-95% for well-structured SRS documents.

Can I customize the generated diagrams?

Currently, diagrams are auto-generated. Manual customization is on the roadmap. You can download and edit them using tools like PlantUML editors.

Is my data secure?
  • All data is processed locally on your server
  • No data is sent to third-party services (except AI API if configured)
  • You have full control over your documents and diagrams
Can I use this in production?

Yes, but ensure you:

  • Set up proper authentication
  • Use HTTPS in production
  • Configure rate limiting
  • Regularly backup your data
What's the difference between Workflow and manual processing?
  • Manual: Step-by-step process (Upload → Process → Extract → Generate)
  • Workflow: One-click automation of all steps with progress tracking
How do I update to the latest version? 
git pull origin main
pnpm install
pnpm build

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2025 Navinda Chandrasiri

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

See LICENSE file for full details.

🙏 Acknowledgments

This project wouldn't be possible without these amazing open-source projects:

Special thanks to:

  • OpenAI for AI capabilities
  • The open-source community
  • All contributors and users

📞 Support

Need Help?

Stay Updated

  • ⭐ Star this repository
  • 👀 Watch for updates
  • 🔔 Enable notifications

🔗 Related Projects

🌟 Star History

Star History Chart

💖 Built with passion by paradocx96

If you find this project helpful, please consider giving it a ⭐

Back to Top ⬆️

Last updated: December 2024

About

SpecMorph is a cutting edge web application that leverages AI to automatically transform Software Requirements Specification (SRS) documents into professional UML diagrams.

specmorph.vercel.app

Topics

ai diagram uml extraction srs

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages