@specverse/engine-realize 3.5.3

package/assets/templates/backend-only/README.md

@@ -0,0 +1,197 @@
+# {{projectName}} - Backend API
+
+A standalone REST API service built with SpecVerse. Perfect for microservices, API-first development, and backend services.
+
+## 🚀 Quick Start
+
+```bash
+# 1. Generate all code
+npm run realize:all
+
+# 2. Install dependencies
+cd generated/code && npm install
+
+# 3. Setup database
+npm run db:generate
+npm run db:push
+
+# 4. Start development server
+npm run dev
+
+# 5. Test the API
+curl http://localhost:3000/api/products
+```
+
+## 📁 Project Structure
+
+```
+{{projectName}}/
+├── specs/
+│   └── main.specly              # Your API specification
+├── manifests/
+│   └── implementation.yaml      # Backend-only manifest
+├── generated/
+│   └── code/                    # Generated backend code
+│       ├── src/
+│       │   ├── main.ts          # Application entry point
+│       │   ├── controllers/     # Business logic
+│       │   └── routes/          # API routes
+│       ├── prisma/
+│       │   └── schema.prisma    # Database schema
+│       ├── package.json         # Dependencies
+│       └── tsconfig.json        # TypeScript config
+└── package.json                 # Workflow scripts
+```
+
+## 🛠️ Development Workflow
+
+### 1. Modify Your API
+
+Edit `specs/main.specly` to define your models and controllers:
+
+```yaml
+models:
+  Product:
+    attributes:
+      name: String required
+      price: Decimal required
+
+controllers:
+  ProductController:
+    model: Product
+    cured:
+      create: {}
+      retrieve: {}
+```
+
+### 2. Regenerate Code
+
+```bash
+npm run realize:all
+```
+
+### 3. Update Database
+
+```bash
+cd generated/code
+npm run db:generate  # Generate Prisma client
+npm run db:push      # Push schema to database
+```
+
+### 4. Run Development Server
+
+```bash
+npm run dev
+```
+
+The API will be available at `http://localhost:3000`
+
+## 📡 API Endpoints
+
+Based on the default Product model:
+
+- `POST /api/products` - Create a product
+- `GET /api/products` - List all products
+- `GET /api/products/:id` - Get a product by ID
+- `PUT /api/products/:id` - Update a product
+- `DELETE /api/products/:id` - Delete a product
+
+## 🔧 Configuration
+
+### Environment Variables
+
+Create a `.env` file in `generated/code/`:
+
+```env
+DATABASE_URL="postgresql://localhost:5432/{{projectNameKebab}}_dev"
+PORT=3000
+CORS_ORIGINS="http://localhost:5173,http://localhost:3000"
+```
+
+### CORS Setup
+
+The backend is configured to accept requests from frontend applications. Update `CORS_ORIGINS` in your `.env` file to match your frontend URL.
+
+## 🧪 Testing
+
+```bash
+# Run tests
+cd generated/code && npm test
+
+# Type checking
+npm run typecheck
+
+# Linting
+npm run lint
+```
+
+## 📦 Deployment
+
+### Standalone Deployment
+
+The generated backend is a standalone Node.js application that can be deployed to:
+
+- **Docker**: Add a Dockerfile to containerize
+- **Cloud Platforms**: Deploy to AWS, GCP, Azure, Railway, Render, etc.
+- **Kubernetes**: Use the generated code as a microservice
+
+### Environment Setup
+
+Set these environment variables in production:
+
+```env
+DATABASE_URL="your-production-database-url"
+PORT=8080
+CORS_ORIGINS="https://your-frontend-domain.com"
+```
+
+## 📚 Documentation
+
+### Generate API Documentation
+
+```bash
+npm run generate:docs
+npm run generate:diagrams
+```
+
+### View Database Schema
+
+```bash
+cd generated/code
+npm run db:studio
+```
+
+This opens Prisma Studio at `http://localhost:5555`
+
+## 🎯 Use Cases
+
+This backend-only template is ideal for:
+
+- **Microservices**: Building focused, single-responsibility services
+- **API-First Development**: Designing APIs before building frontends
+- **Mobile Backends**: Serving iOS, Android, or cross-platform apps
+- **Third-Party Integrations**: Providing APIs for external consumers
+- **Serverless Functions**: Base code for AWS Lambda, Vercel Functions, etc.
+
+## 🔄 Connecting Frontends
+
+Your frontend applications can connect to this API using:
+
+```typescript
+// Frontend configuration
+const API_BASE_URL = process.env.VITE_API_BASE_URL || 'http://localhost:3000';
+
+// Fetch products
+const response = await fetch(`${API_BASE_URL}/api/products`);
+const products = await response.json();
+```
+
+## 📖 Learn More
+
+- [SpecVerse Documentation](https://specverse.dev)
+- [API Guide](./docs/)
+- [Database Migrations](./generated/code/prisma/migrations/)
+
+---
+
+Built with ❤️ using [SpecVerse](https://specverse.dev)

package/assets/templates/backend-only/deployments/README.md

@@ -0,0 +1,149 @@
+# Deployments Directory
+
+This directory can be used to organize deployment specifications when you need multiple deployment targets or environment-specific configurations.
+
+## Usage
+
+Deployments can be organized by environment, scale, or target platform:
+
+1. **Environment-based organization**:
+   ```
+   deployments/
+   ├── development.specly
+   ├── staging.specly
+   └── production.specly
+   ```
+
+2. **Scale-based organization**:
+   ```
+   deployments/
+   ├── personal.specly      # Single developer, local database
+   ├── team.specly          # Small team, shared database
+   ├── business.specly      # Business scale, clustering
+   └── enterprise.specly    # Enterprise scale, multi-tenant
+   ```
+
+3. **Platform-based organization**:
+   ```
+   deployments/
+   ├── local.specly         # Local development
+   ├── cloud.specly         # Cloud deployment (AWS, GCP, Azure)
+   ├── kubernetes.specly    # Kubernetes clusters
+   └── serverless.specly    # Serverless functions
+   ```
+
+## Deployment Patterns
+
+### Based on SpecVerse Library Patterns
+
+You can reference deployment patterns from the SpecVerse library system:
+
+- **Monolith Pattern**: Single-instance deployment (from `libs/deployments/monolith/`)
+- **Microservices Pattern**: Service-based deployment (from `libs/deployments/microservices/`)
+- **JAMstack Pattern**: Static + API deployment (from `libs/deployments/jamstack/`)
+- **Enterprise Pattern**: Multi-tenant, compliance-ready (from `libs/deployments/enterprise/`)
+
+### Example Deployment Structure
+
+```yaml
+# deployments/development.specly
+components:
+  my-app-dev:
+    version: "3.1.0"
+    
+    # Reference library patterns
+    import:
+      - file: ../../../libs/deployments/monolith/lib/development.yaml
+        select: ["development"]
+    
+    deployments:
+      development:
+        version: "3.1.0"
+        environment: "development"
+        
+        # Based on monolith development pattern
+        instances:
+          controllers:
+            appController:
+              component: "my-app"
+              namespace: "api"
+              scale: 1
+              advertises: ["api.*"]
+              uses: ["database.*"]
+```
+
+## Instance Types
+
+SpecVerse v3.3 supports these logical instance types:
+
+- **Controllers**: API endpoints, request handlers
+- **Services**: Business logic, background processing
+- **Views**: UI components, frontend applications
+- **Storage**: Databases, caches, file systems
+- **Security**: Authentication, authorization, encryption
+- **Infrastructure**: Load balancers, CDNs, service mesh
+- **Monitoring**: Metrics, logging, alerting, analytics
+- **Communications**: Message queues, event buses, RPC channels
+
+## Capability Patterns
+
+Use capability patterns to define instance communication:
+
+```yaml
+instances:
+  controllers:
+    apiController:
+      advertises: ["api.*", "auth.*"]     # What this instance provides
+      uses: ["database.*", "cache.*"]     # What this instance depends on
+```
+
+## Scaling Configuration
+
+Define scaling behavior for different environments:
+
+```yaml
+instances:
+  controllers:
+    webApi:
+      scale: 3                          # Number of instances
+      advertises: ["api.*"]
+      uses: ["database.*"]
+      config:
+        resources:
+          memory: "512Mi"
+          cpu: "200m"
+        healthCheck:
+          path: "/health"
+          interval: "30s"
+```
+
+## Import Examples
+
+```yaml
+# In main.specly, reference deployment specifications
+deployments:
+  development:
+    import:
+      - file: deployments/development.specly
+        select: ["development"]
+  
+  production:
+    import:
+      - file: deployments/production.specly
+        select: ["production"]
+```
+
+## Best Practices
+
+1. **Environment Separation**: Keep development and production deployments separate
+2. **Library Usage**: Reference standard patterns from `libs/deployments/`
+3. **Capability Design**: Use clear advertises/uses patterns for dependencies
+4. **Scaling Strategy**: Define appropriate scaling for each environment
+5. **Security Layering**: Include security instances for authentication and authorization
+6. **Monitoring Integration**: Add monitoring instances for production deployments
+
+## See Also
+
+- **Library Patterns**: `../../libs/deployments/` for standard deployment patterns
+- **Manifests**: `../manifests/` for technology-specific implementation guidance
+- **Main Specification**: `../specs/main.specly` for component definitions

package/assets/templates/backend-only/deployments/development.specly

@@ -0,0 +1,53 @@
+# Development Deployment
+# SpecVerse v3.3 deployment specification for local development
+
+deployments:
+  development:
+    version: "1.0.0"
+    environment: "development"
+    description: "Local development deployment with SQLite"
+    
+    # Based on libs/deployments/monolith/development pattern
+    instances:
+      controllers:
+        appController:
+          component: "{{componentName}}"
+          namespace: "api"
+          scale: 1
+          advertises: ["api.*"]
+          uses: ["database.*", "auth.*"]
+          
+      services:
+        appService:
+          component: "{{componentName}}"
+          namespace: "services"
+          scale: 1
+          advertises: ["business.*", "validation.*"]
+          uses: ["database.*"]
+          
+      storage:
+        localDB:
+          component: "{{componentName}}"
+          namespace: "data"
+          type: "relational"
+          scale: 1
+          advertises: ["persistence.*", "query.*"]
+          
+      security:
+        devAuth:
+          component: "{{componentName}}"
+          namespace: "auth"
+          type: "authentication"
+          provider: "local"
+          scope: "component"
+          scale: 1
+          advertises: ["auth.*"]
+          policies: ["dev-access"]
+          encryption: "basic"
+          auditLevel: "basic"
+          
+      communications:
+        localBus:
+          namespace: "local"
+          type: "rpc"
+          capabilities: ["*"]

package/assets/templates/backend-only/deployments/production.specly

@@ -0,0 +1,87 @@
+# Production Deployment
+# SpecVerse v3.1 deployment specification for production environment
+
+deployments:
+  production:
+    version: "1.0.0"
+    environment: "production"
+    description: "Production deployment with PostgreSQL and monitoring"
+    
+    # Based on libs/deployments/monolith/production pattern
+    instances:
+      controllers:
+        apiServer:
+          component: "{{componentName}}"
+          namespace: "api"
+          scale: 3
+          advertises: ["api.*"]
+          uses: ["database.*", "auth.*", "cache.*"]
+          
+      services:
+        businessService:
+          component: "{{componentName}}"
+          namespace: "services"
+          scale: 2
+          advertises: ["business.*", "validation.*"]
+          uses: ["database.*", "cache.*"]
+          
+      storage:
+        mainDB:
+          component: "{{componentName}}"
+          namespace: "data"
+          type: "relational"
+          scale: 2
+          backup: true
+          encryption: true
+          advertises: ["persistence.*", "query.*"]
+          
+        cache:
+          component: "{{componentName}}"
+          namespace: "cache"
+          type: "keyvalue"
+          scale: 2
+          advertises: ["cache.*", "session.*"]
+          
+      security:
+        authSystem:
+          component: "{{componentName}}"
+          namespace: "auth"
+          type: "authentication"
+          provider: "oauth"
+          scope: "global"
+          scale: 2
+          advertises: ["auth.*", "identity.*"]
+          policies: ["session-management", "rate-limiting"]
+          encryption: "strong"
+          auditLevel: "detailed"
+          
+      monitoring:
+        appMetrics:
+          component: "{{componentName}}"
+          namespace: "monitoring"
+          type: "metrics"
+          provider: "prometheus"
+          scope: "global"
+          retention: "medium"
+          resolution: "high"
+          advertises: ["metrics.*"]
+          dashboards: ["overview", "errors", "performance"]
+          alerts: ["high-error-rate", "service-down", "high-latency"]
+          
+      infrastructure:
+        loadBalancer:
+          component: "{{componentName}}"
+          namespace: "gateway"
+          type: "gateway"
+          provider: "nginx"
+          tier: "regional"
+          redundancy: "basic"
+          advertises: ["routing.*", "balancing.*"]
+          protocols: ["http", "https"]
+          healthChecks: true
+          
+      communications:
+        prodBus:
+          namespace: "global"
+          type: "pubsub"
+          capabilities: ["*"]

package/assets/templates/backend-only/docs/README.md

@@ -0,0 +1,50 @@
+# {{projectName}} Documentation
+
+This directory contains project-specific documentation for your SpecVerse application.
+
+## Documentation Structure
+
+```
+docs/
+├── README.md                           # This file
+├── example-documentation-template.md   # Template for creating documentation
+├── api/                               # API documentation (generated)
+├── diagrams/                          # Generated diagrams
+└── guides/                            # Project-specific guides
+```
+
+## Generated Content
+
+When you run SpecVerse generation commands, documentation will be created in:
+
+- `diagrams/` - UML diagrams (ER, sequence, architecture, lifecycle, deployment)
+- `api/` - API documentation generated from specifications
+
+## SpecVerse Schema Reference
+
+For complete SpecVerse language documentation and schema reference, see:
+
+- **Main Schema**: `../../schema/SPECVERSE-SCHEMA.json`
+- **Schema Guidance**: Maintained in the main project
+
+These files contain the authoritative SpecVerse v3.3 language specification and are maintained in the main project.
+
+## Creating Project Documentation
+
+1. Use `example-documentation-template.md` as a starting point
+2. Run `npm run generate:docs` to generate API documentation
+3. Run `npm run generate:diagrams` to create visual diagrams
+4. Add project-specific guides in the `guides/` directory
+
+## Generation Commands
+
+```bash
+# Generate all documentation
+npm run generate:docs
+
+# Generate diagrams only
+npm run generate:diagrams
+
+# Generate specific diagram types
+npm run generate:diagram:deployment
+```

package/assets/templates/backend-only/docs/api/README.md

@@ -0,0 +1,7 @@
+# API Documentation
+
+Generated API documentation will appear here when you run:
+
+```bash
+npm run generate:docs
+```

package/assets/templates/backend-only/docs/diagrams/README.md

@@ -0,0 +1,85 @@
+# Generated Diagrams
+
+This directory contains auto-generated Mermaid diagrams from your SpecVerse specification.
+
+## Diagram Types
+
+### Entity-Relationship (er-diagram)
+Shows models, attributes, and relationships.
+
+**Generate**: `npm run generate:diagram:er`
+**Best For**: Understanding data structure
+
+### Event-Flow-Layered (event-flow-layered)
+Shows event-driven architecture with topological sorting.
+
+**Generate**: `npm run generate:diagram:event-flow`
+**Best For**: Understanding event flow and component dependencies
+**Features**:
+- Dynamic layer assignment based on dependency depth
+- Topological sorting for proper component ordering
+- Color-coded domain vs application events
+- Simplified labels showing event counts (↑ publishes, ↓ subscribes)
+
+### Lifecycle (lifecycle)
+Shows state machine transitions for model lifecycles.
+
+**Generate**: `npm run generate:diagram:lifecycle`
+**Best For**: Understanding state transitions
+
+### Deployment (deployment-topology)
+Shows deployment instances and capability mappings.
+
+**Generate**: `npm run generate:diagram:deployment`
+**Best For**: Understanding deployment architecture
+
+### Model Architecture (model-architecture)
+Shows component relationships and dependencies.
+
+**Generate**: `npm run generate:diagram:architecture`
+**Best For**: High-level system overview
+
+## Viewing Diagrams
+
+Mermaid diagrams can be viewed in:
+- **GitHub**: Automatically rendered in .md files
+- **VSCode**: Use Markdown Preview Mermaid Support extension
+- **Mermaid Live Editor**: https://mermaid.live/
+- **Documentation Sites**: Most support Mermaid rendering
+
+## Programmatic Generation
+
+```typescript
+import { UnifiedDiagramGenerator, EventFlowPlugin } from '@specverse/lang/diagram-engine';
+import { SpecVerseParser } from '@specverse/lang';
+import { readFileSync, writeFileSync } from 'fs';
+
+// 1. Parse your specification
+const schema = JSON.parse(
+  readFileSync('node_modules/@specverse/lang/schema/SPECVERSE-SCHEMA.json', 'utf8')
+);
+const parser = new SpecVerseParser(schema);
+const parseResult = parser.parseFile('specs/main.specly');
+
+// 2. Create diagram generator with desired plugins
+const generator = new UnifiedDiagramGenerator({
+  plugins: [
+    new EventFlowPlugin(),
+    new ERDiagramPlugin(),
+    new LifecyclePlugin(),
+    new DeploymentPlugin()
+  ],
+  theme: 'default'
+});
+
+// 3. Generate specific diagram type
+const mermaidCode = generator.generate(parseResult.ast, 'event-flow-layered', {
+  title: 'Event Flow Architecture',
+  direction: 'TD'
+});
+
+// 4. Save to file
+writeFileSync('docs/diagrams/event-flow-layered.mmd', mermaidCode);
+```
+
+See [example 11-diagrams documentation](https://github.com/SpecVerse/specverse-lang/tree/main/examples/11-diagrams) for complete API reference and more examples