███████╗██████╗ ███████╗ ██████╗██████╗ ██████╗██╗ ██████╗ ██╗ ██╗██████╗
██╔════╝██╔══██╗██╔════╝██╔════╝╚════██╗██╔════╝██║ ██╔═══██╗██║ ██║██╔══██╗
███████╗██████╔╝█████╗ ██║ █████╔╝██║ ██║ ██║ ██║██║ ██║██║ ██║
╚════██║██╔═══╝ ██╔══╝ ██║ ██╔═══╝ ██║ ██║ ██║ ██║██║ ██║██║ ██║
███████║██║ ███████╗╚██████╗███████╗╚██████╗███████╗╚██████╔╝╚██████╔╝██████╔╝
╚══════╝╚═╝ ╚══════╝ ╚═════╝╚══════╝ ╚═════╝╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝
A radical journey through spec-driven development where documentation drives the future 🚀
Welcome to the Spec2Cloud Introduction Lab, where we flip traditional development on its head! Instead of code-first development where documentation comes later (or never 😅), we embrace spec-driven development where specifications are the primary artifacts that drive everything else.
Think of it like this: in the retro arcade era, game designers started with specifications and design documents. Those specs drove the implementation. We're bringing that philosophy to cloud modernization! 🕹️✨
Spec2Cloud is a radical approach to application modernization where:
- 📋 Specifications come FIRST — Architecture docs, API contracts, and data models are the source of truth
- 🤖 AI assists extraction — Analyze legacy code to generate specs automatically
- 🎨 Specs drive generation — Use those specs to build modern implementations
- ☁️ Cloud-native from specs — Deploy to cloud platforms guided by your architecture specs
In this lab, you'll use the OpenShelf Library — a retro library management app — as your teaching playground! 📚
By completing this lab, you'll unlock these achievements:
- 💭 Spec-Driven Philosophy — Understand why specs-first beats code-first
- 🛠️ Spec2Cloud Toolchain — Install and configure the complete toolkit
- 🔍 Legacy Code Analysis — Point AI at old code and extract architectural knowledge
- 📐 Architecture Specifications — Generate system architecture documents
- 🔌 API Contract Generation — Create OpenAPI specs from existing endpoints
- 🗄️ Data Model Extraction — Document entity relationships and schemas
- 🚀 Modernization Roadmap — Use specs to guide your cloud migration
- ✅ Spec Validation — Ensure implementations match specifications
ACHIEVEMENT UNLOCKED: SPEC MASTER 🏆
Before you insert your coin and start playing, make sure you have:
- ✅ Node.js 18+ installed (Download here)
- ✅ Git CLI installed (Download here)
- ✅ Markdown proficiency (basic reading/writing)
- ✅ GitHub Copilot CLI installed (Setup guide)
- ✅ Visual Studio Code (or your favorite editor)
- ✅ A sense of adventure 🎢
POWER-UP READY! ⚡
LOADING LEVEL 1... ▓▓▓▓▓▓▓▓░░ 80%
Get the OpenShelf Library running in 3... 2... 1... GO! 🏁
# Clone the repository
git clone https://github.com/EmeaAppGbb/appmodlab-spec2cloud-introduction.git
# Enter the game world
cd appmodlab-spec2cloud-introduction
# Install power-ups (dependencies)
npm install
# START THE GAME! 🎮
npm start🌐 Browse to: http://localhost:3000
SYSTEM ONLINE ✨ You should see the OpenShelf Library running!
appmodlab-spec2cloud-introduction/
│
├── 📂 src/ # Legacy application source code
│ ├── app.js # Main Express server
│ ├── routes/ # API route handlers
│ ├── models/ # In-memory data models
│ └── public/ # Frontend HTML/CSS/JS
│
├── 📂 specs/ # 🎯 TARGET: Your generated specs go here!
│ ├── architecture/ # System architecture documents
│ ├── api/ # OpenAPI/Swagger contracts
│ └── data/ # Entity relationship diagrams & schemas
│
├── 📂 tests/ # Test suites
│
├── package.json # Node.js dependencies
└── README.md # You are here! 👋
LEVEL MAP LOADED 🗺️
The OpenShelf Library is a retro-styled library management system. It's intentionally simple but demonstrates real-world patterns perfect for spec extraction:
Core Features:
- 📚 Book Catalog — Browse, search, and view book details
- 👥 Member Management — Register members and track accounts
- 🔄 Loan Tracking — Check out books, return them, track due dates
- 📊 Simple Reporting — View loan history and popular books
Tech Stack (Legacy):
- 🟢 Node.js 14 (older version)
- 🚂 Express.js (classic web framework)
- 💾 In-Memory Storage (arrays/objects, no database!)
- 🎨 Vanilla JavaScript frontend
- 📋 No API documentation (the horror! 😱)
Why this app? It's complex enough to have meaningful architecture, APIs, and data models, but simple enough to understand in an afternoon. Perfect for learning Spec2Cloud! 🎯
Here's what the legacy OpenShelf Library looks like when running:
Homepage — Dashboard with live statistics:
Book Catalog — Full inventory with search, genre badges, and availability tracking:
Add New Book — Form for adding books to the catalog:
Library Members — Member directory with status management:
Book Loans — Active loans with status cards and filtering:
Checkout — Book checkout form with member and book selection:
LOADING NEXT LEVEL... ▓▓▓▓▓▓▓░░░ 90%
Philosophy Time! 🧘♂️
Traditional development:
Code → (maybe) Docs → (hopefully) Architecture Understanding → Cloud Migration 😰
Spec-Driven Development:
Specs → Clean Architecture → Modern Code → Cloud-Native Deployment 😎
Why Specs First?
- 🎯 Single Source of Truth — Specs define the "what" independent of the "how"
- 🤖 AI-Friendly — Modern AI excels at working with structured specifications
- 🔄 Technology Agnostic — Same specs, multiple implementations (Node, Python, Java, etc.)
- ☁️ Cloud-Ready — Specs map naturally to cloud services and infrastructure
- 📚 Documentation that Lives — Specs ARE the documentation, always in sync
INSIGHT GAINED 💡
MISSION: Get familiar with what you're modernizing!
-
Start the app (if not already running):
npm start
-
Browse the catalog 📚
- Open http://localhost:3000
- Check out the book listing
- Click into a book to see details
-
Register a member 👤
- Click "Members" in the nav
- Add a new member (use your name!)
- Note the member ID
-
Check out a book 📤
- Go back to books
- Click "Check Out" on any book
- Enter your member ID
- Success! You've borrowed a book! 🎉
-
Return the book 📥
- Click "Return" on the same book
- Boom! Clean slate!
WORLD EXPLORED 🗺️ You now understand the user experience!
POWER-UP TIME! ⚡
The Spec2Cloud toolchain works through GitHub Copilot CLI. Let's set it up:
-
Verify Copilot CLI is installed:
gh copilot --version
-
Initialize Spec2Cloud in your project:
# Use Copilot CLI to bootstrap Spec2Cloud gh copilot suggest "Set up Spec2Cloud for analyzing a Node.js Express application"
-
Verify the setup:
# Check that spec directories exist ls -la specs/
TOOLCHAIN READY 🔧
TIME TO SCAN THE CODEBASE! 🔍
Use Spec2Cloud to analyze the legacy app:
# Analyze the entire src/ directory
gh copilot "Analyze the Node.js application in ./src and generate architecture specifications. Save to ./specs/architecture/"What's happening?
- 🤖 AI reads your source code
- 🧠 Identifies patterns, components, and relationships
- 📝 Generates structured specification documents
- 💾 Saves them to your specs/ folder
SCAN COMPLETE ✅
BOSS ENCOUNTER: THE ARCHITECTURE DOCUMENT 🐉
Navigate to specs/architecture/ and open the generated architecture spec:
cd specs/architecture
# Open the generated markdown file
code system-architecture.mdWhat to look for:
- 🏗️ System Components — Server, routes, models, frontend
- 🔗 Component Interactions — How pieces talk to each other
- 💾 Data Flow — Where data comes from and goes to
- 🎯 Design Patterns — MVC? REST? What patterns are in use?
⚠️ Technical Debt — What needs modernization?
Example findings:
- "In-memory storage creates scalability bottleneck" 📊
- "No API versioning strategy" 🔢
- "Frontend tightly coupled to backend" 🔗
ARCHITECTURE MAPPED 🗺️
MISSION: DOCUMENT THE APIs 📡
Check out the generated API specifications:
cd specs/api
# View the OpenAPI spec
code openapi.yamlWhat you'll see:
- 🛣️ Endpoints — GET /books, POST /members, etc.
- 📥 Request Schemas — What data to send
- 📤 Response Schemas — What data you get back
⚠️ Error Responses — 404, 500, etc.- 🔐 Security — Authentication/authorization (or lack thereof!)
Example endpoint:
/api/books:
get:
summary: List all books
responses:
200:
description: Array of books
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Book'API CONTRACT LOCKED 🔒
EXAMINE THE DATA LAYER 💾
Open the data model specifications:
cd specs/data
# Check entity models
code entity-model.mdWhat's documented:
- 📊 Entities — Book, Member, Loan
- 🔑 Attributes — Fields and data types
- 🔗 Relationships — One-to-many, many-to-many
- 📐 Constraints — Required fields, validations
- 🗃️ Current Implementation — In-memory arrays (scary!)
Example entity:
### Book
- id: String (unique)
- title: String (required)
- author: String (required)
- isbn: String
- available: Boolean
- checkedOutBy: String (Member ID, nullable)DATA MODEL EXTRACTED 🎯
CUSTOMIZE YOUR DESTINY ✨
Now the magic happens! Edit the specs to guide modernization:
-
Open architecture spec and add modernization notes:
## Target Architecture - ✅ Migrate from Express → Fastify (better performance) - ✅ Replace in-memory storage → PostgreSQL - ✅ Add Redis caching layer - ✅ Containerize with Docker
-
Enhance API specs with new requirements:
# Add authentication security: - bearerAuth: [] # Add pagination parameters: - name: page in: query schema: type: integer
-
Update data models for the database:
### Book (PostgreSQL Schema) - id: UUID PRIMARY KEY - title: VARCHAR(255) NOT NULL - author: VARCHAR(255) NOT NULL - isbn: VARCHAR(13) UNIQUE - available: BOOLEAN DEFAULT true - created_at: TIMESTAMP - updated_at: TIMESTAMP
SPECS REFINED 💎
RECONSTRUCTION TIME! 🏗️
Use the refined specs to guide building the modern version:
# Create a new modern implementation folder
mkdir modern-implementation
cd modern-implementation
# Initialize new Node.js project
npm init -y
# Install modern stack
npm install fastify @fastapi/postgres @fastapi/redis
# Use Copilot to generate code from specs
gh copilot "Generate a Fastify server implementation based on the OpenAPI spec at ../specs/api/openapi.yaml"What's different?
- 🚀 Fastify instead of Express (faster!)
- 🐘 PostgreSQL instead of in-memory (persistent!)
- 📦 TypeScript for type safety
- 🐳 Docker for containerization
- ☁️ Cloud-ready architecture
NEW IMPLEMENTATION RISING 🌅
FINAL BOSS: VERIFICATION 👾
Ensure your new implementation matches the specs:
-
Run API contract tests:
# Install OpenAPI validator npm install --save-dev jest-openapi # Run tests against the spec npm test
-
Check database schema:
# Compare PostgreSQL schema to data model spec psql -d openshelf -c "\d books"
-
Verify functionality:
- Browse books ✅
- Register members ✅
- Check out/return ✅
- Performance better ✅
- Data persists ✅
ALL SYSTEMS GREEN 🟢
🎊 CONGRATULATIONS! LEVEL COMPLETE! 🎊
THE FINAL FORM 🦋
Your modernized OpenShelf Library will be:
┌─────────────────────────────────────────┐
│ 🌐 Cloud Load Balancer │
└─────────────────┬───────────────────────┘
│
┌─────────────────▼───────────────────────┐
│ 🐳 Docker Container (Fastify App) │
│ ┌────────────────────────────────┐ │
│ │ Node.js 20 + Fastify │ │
│ │ - REST API endpoints │ │
│ │ - JWT authentication │ │
│ │ - Input validation │ │
│ └────┬──────────────────┬────────┘ │
└─────────┼──────────────────┼────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ 🐘 PostgreSQL │ │ 🔴 Redis │
│ - Books │ │ - Sessions │
│ - Members │ │ - Cache │
│ - Loans │ └──────────────────┘
└─────────────────┘
Tech Stack:
- Runtime: Node.js 20 LTS
- Framework: Fastify 4.x
- Database: PostgreSQL 15
- Cache: Redis 7
- Container: Docker + Docker Compose
- Cloud: Azure Container Apps / AWS ECS / GCP Cloud Run
EVOLUTION COMPLETE 🚀
TIME TO BEAT: 2-3 hours ⏰
Speedrun Categories:
- 🥉 Bronze (Casual): 3+ hours — Take your time, enjoy the journey
- 🥈 Silver (Normal): 2-3 hours — Steady pace, good understanding
- 🥇 Gold (Expert): 1-2 hours — You've done this before!
- 💎 Diamond (Speedrun): <1 hour — Spec2Cloud master! 🏆
READY PLAYER ONE? 🎮
KNOWLEDGE BASE UNLOCKED 🔓
- Swagger Editor — Edit OpenAPI specs visually
- dbdiagram.io — Design database schemas
- GitHub Copilot CLI — AI pair programmer
Track your progress:
- 🎯 Started the legacy app
- 🔍 Explored the codebase
- 🛠️ Installed Spec2Cloud toolchain
- 📐 Generated architecture specs
- 🔌 Generated API contracts
- 🗄️ Generated data models
- ✨ Refined specs for modernization
- 🏗️ Built modern implementation
- ✅ Validated against specs
- 🚀 Deployed to cloud
COMPLETE ALL ACHIEVEMENTS TO BECOME A SPEC2CLOUD WIZARD 🧙♂️✨
FOR THE BRAVE ⚔️
- 🔐 Security Quest — Add JWT authentication to all endpoints
- 📊 Analytics Arena — Add book popularity tracking and reporting
- 🔍 Search Saga — Implement full-text search with Elasticsearch
- 🌐 Multi-Tenant Mission — Support multiple libraries in one system
- 📱 Mobile Madness — Create a React Native app using your API specs
- 🤖 AI Assistant — Add a chatbot that recommends books
EXTRA LIVES EARNED 🍄
██████╗ ██████╗ ███╗ ██╗ ██████╗ ██████╗ █████╗ ████████╗███████╗██╗
██╔════╝██╔═══██╗████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝██╔════╝██║
██║ ██║ ██║██╔██╗ ██║██║ ███╗██████╔╝███████║ ██║ ███████╗██║
██║ ██║ ██║██║╚██╗██║██║ ██║██╔══██╗██╔══██║ ██║ ╚════██║╚═╝
╚██████╗╚██████╔╝██║ ╚████║╚██████╔╝██║ ██║██║ ██║ ██║ ███████║██╗
╚═════╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚══════╝╚═╝
You've mastered Spec-Driven Development and unlocked the power of Spec2Cloud! 🎉
Your Score: LEGENDARY 💯 Rank: Spec Master 🏆 Next Level: Production deployment! ☁️
Stuck? No worries! 🤗
- 💬 Ask in GitHub Discussions
- 🐛 Report bugs in Issues
- 📧 Email the lab team: appmod-labs@microsoft.com
- 🤖 Use GitHub Copilot CLI:
gh copilot explain "how does spec2cloud work?"
WE'RE HERE TO HELP! 🤝
MIT License - Share, modify, and enjoy! 🎉
Created with 💜 by:
- Marco Antonio Silva — Lab Designer 🎨
- The Azure App Modernization GBB Team 🚀
- GitHub Copilot — AI Assistant 🤖
- You — The Spec2Cloud Pioneer! 👋
Special Thanks:
- The Node.js community 🟢
- The OpenAPI Initiative 📋
- Everyone who believes specs > chaos ✨
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓ ▓
▓ THANK YOU FOR PLAYING! ▓
▓ INSERT COIN TO CONTINUE... 🪙 ▓
▓ ▓
▓ → Next Lab: Spec2Cloud Advanced ▓
▓ → Coming Soon: Multi-Cloud Deploy ▓
▓ ▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
PRESS START TO BEGIN YOUR SPEC2CLOUD JOURNEY 🎮✨
Made with ❤️ and a whole lot of ☕ in 2024