fragment-ts 1.0.2 → 1.0.3

package/USAGE.md

@@ -0,0 +1,1439 @@
+# Fragment Framework - Comprehensive Use Cases & Examples
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Basic REST API](#basic-rest-api)
+- [Authentication & Authorization](#authentication--authorization)
+- [Database Operations](#database-operations)
+- [AI-Powered Applications](#ai-powered-applications)
+- [Dependency Injection Patterns](#dependency-injection-patterns)
+- [Advanced Routing](#advanced-routing)
+- [Custom Middleware](#custom-middleware)
+- [Testing](#testing)
+- [Production Deployment](#production-deployment)
+- [CLI Reference](#cli-reference)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick Start
+
+### Installation & Project Initialization
+
+```bash
+# Install Fragment CLI globally
+npm install -g fragment
+
+# Option 1: Initialize in current directory
+mkdir my-app && cd my-app
+fragment init .
+
+# Option 2: Create new directory and initialize
+fragment init my-app
+cd my-app
+
+# Option 3: Use specific template
+fragment init my-api --template=api
+
+# Option 4: Select features interactively
+fragment init my-app --features=auth,ai,database
+
+# Option 5: Skip npm install (install manually later)
+fragment init my-app --skip-install
+```
+
+**Yes, `fragment init .` initializes in the current directory!**
+
+### Start Development
+
+```bash
+# Start with hot reload (auto-restarts on file changes)
+fragment serve
+
+# Start on custom port
+fragment serve --port=4000
+
+# Start without watch mode
+fragment serve --no-watch
+
+# Build for production
+fragment build
+
+# Run production build
+npm start
+```
+
+---
+
+## Basic REST API
+
+### Use Case 1: Simple CRUD API
+
+Create a complete REST API for managing products.
+
+```bash
+# Generate complete resource (controller, service, entity, DTO, repository)
+fragment generate resource product
+
+# Or use shorthand
+fragment g resource product
+```
+
+**Generated Files:**
+
+**src/controllers/product.controller.ts**
+
+```typescript
+import { Controller, Get, Post, Put, Delete, Body, Param } from "fragment";
+import { ProductService } from "../services/product.service";
+
+@Controller("/products")
+export class ProductController {
+  constructor(private productService: ProductService) {}
+
+  @Get()
+  async findAll() {
+    return this.productService.findAll();
+  }
+
+  @Get("/:id")
+  async findOne(@Param("id") id: string) {
+    return this.productService.findOne(id);
+  }
+
+  @Post()
+  async create(@Body() body: any) {
+    return this.productService.create(body);
+  }
+
+  @Put("/:id")
+  async update(@Param("id") id: string, @Body() body: any) {
+    return this.productService.update(id, body);
+  }
+
+  @Delete("/:id")
+  async delete(@Param("id") id: string) {
+    return this.productService.delete(id);
+  }
+}
+```
+
+**src/services/product.service.ts**
+
+```typescript
+import { Service } from "fragment";
+import { ProductRepository } from "../repositories/product.repository";
+
+@Service()
+export class ProductService {
+  constructor(private productRepository: ProductRepository) {}
+
+  async findAll() {
+    return this.productRepository.findAll();
+  }
+
+  async findOne(id: string) {
+    const product = await this.productRepository.findById(parseInt(id));
+    if (!product) {
+      throw new Error("Product not found");
+    }
+    return product;
+  }
+
+  async create(data: any) {
+    return this.productRepository.create(data);
+  }
+
+  async update(id: string, data: any) {
+    return this.productRepository.update(parseInt(id), data);
+  }
+
+  async delete(id: string) {
+    return this.productRepository.delete(parseInt(id));
+  }
+}
+```
+
+**src/entities/product.entity.ts**
+
+```typescript
+import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
+
+@Entity()
+export class Product {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column()
+  name: string;
+
+  @Column("decimal", { precision: 10, scale: 2 })
+  price: number;
+
+  @Column({ nullable: true })
+  description: string;
+
+  @Column({ default: 0 })
+  stock: number;
+
+  @Column({ type: "timestamp", default: () => "CURRENT_TIMESTAMP" })
+  createdAt: Date;
+
+  @Column({ type: "timestamp", default: () => "CURRENT_TIMESTAMP" })
+  updatedAt: Date;
+}
+```
+
+**Testing the API:**
+
+```bash
+# Start server
+fragment serve
+
+# Verify routes are registered
+fragment routes
+
+# Test endpoints
+curl http://localhost:3000/products
+curl -X POST http://localhost:3000/products \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Laptop","price":999.99,"stock":10}'
+curl http://localhost:3000/products/1
+curl -X PUT http://localhost:3000/products/1 \
+  -H "Content-Type: application/json" \
+  -d '{"price":899.99}'
+curl -X DELETE http://localhost:3000/products/1
+```
+
+---
+
+## Authentication & Authorization
+
+### Use Case 2: User Authentication System
+
+Complete authentication with JWT tokens, password hashing, and role-based access.
+
+```bash
+# Initialize with auth feature
+fragment init auth-api --features=auth,database
+cd auth-api
+
+# Generate user resource
+fragment generate resource user
+```
+
+**src/entities/user.entity.ts**
+
+```typescript
+import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
+
+@Entity()
+export class User {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column({ unique: true })
+  email: string;
+
+  @Column()
+  password: string;
+
+  @Column()
+  name: string;
+
+  @Column("simple-array", { default: "user" })
+  roles: string[];
+
+  @Column({ type: "timestamp", default: () => "CURRENT_TIMESTAMP" })
+  createdAt: Date;
+}
+```
+
+**src/services/auth.service.ts**
+
+```typescript
+import { Service } from "fragment";
+import { AuthModule, NotFoundError, UnauthorizedError } from "fragment";
+import { UserRepository } from "../repositories/user.repository";
+
+@Service()
+export class AuthService {
+  constructor(private userRepository: UserRepository) {}
+
+  async register(email: string, password: string, name: string) {
+    // Hash password
+    const hashedPassword = await AuthModule.hashPassword(password);
+
+    // Create user
+    const user = await this.userRepository.create({
+      email,
+      password: hashedPassword,
+      name,
+      roles: ["user"],
+    });
+
+    // Generate token
+    const token = AuthModule.generateToken({
+      userId: user.id.toString(),
+      email: user.email,
+      roles: user.roles,
+    });
+
+    return { user: { id: user.id, email, name }, token };
+  }
+
+  async login(email: string, password: string) {
+    // Find user
+    const user = await this.userRepository.findByEmail(email);
+    if (!user) {
+      throw new UnauthorizedError("Invalid credentials");
+    }
+
+    // Verify password
+    const isValid = await AuthModule.comparePassword(password, user.password);
+    if (!isValid) {
+      throw new UnauthorizedError("Invalid credentials");
+    }
+
+    // Generate token
+    const token = AuthModule.generateToken({
+      userId: user.id.toString(),
+      email: user.email,
+      roles: user.roles,
+    });
+
+    return { user: { id: user.id, email, name: user.name }, token };
+  }
+
+  async getCurrentUser(userId: string) {
+    const user = await this.userRepository.findById(parseInt(userId));
+    if (!user) {
+      throw new NotFoundError("User not found");
+    }
+    return { id: user.id, email: user.email, name: user.name };
+  }
+}
+```
+
+**src/controllers/auth.controller.ts**
+
+```typescript
+import { Controller, Post, Get, Body, Req } from "fragment";
+import { AuthModule } from "fragment";
+import { AuthService } from "../services/auth.service";
+
+@Controller("/auth")
+export class AuthController {
+  constructor(private authService: AuthService) {}
+
+  @Post("/register")
+  async register(@Body() body: any) {
+    return this.authService.register(body.email, body.password, body.name);
+  }
+
+  @Post("/login")
+  async login(@Body() body: any) {
+    return this.authService.login(body.email, body.password);
+  }
+}
+
+@Controller("/api")
+export class ProtectedController {
+  constructor(private authService: AuthService) {}
+
+  // Protected route - requires authentication
+  @Get("/me")
+  async getProfile(@Req() req: any) {
+    // In production, use middleware to attach user to request
+    const authHeader = req.headers.authorization;
+    if (!authHeader) {
+      throw new UnauthorizedError("Missing authorization header");
+    }
+
+    const token = authHeader.replace("Bearer ", "");
+    const payload = AuthModule.verifyToken(token);
+
+    return this.authService.getCurrentUser(payload.userId);
+  }
+}
+```
+
+**src/main.ts - Add Auth Middleware**
+
+```typescript
+import "reflect-metadata";
+import { FragmentApplication } from "fragment";
+import { FragmentWebApplication } from "fragment";
+import { AuthModule } from "fragment";
+
+@FragmentApplication({
+  port: 3000,
+  autoScan: true,
+})
+class Application {}
+
+async function bootstrap() {
+  const app = new FragmentWebApplication();
+
+  // Apply auth middleware to protected routes
+  const expressApp = app.getExpressApp();
+  expressApp.use("/api/*", AuthModule.authMiddleware());
+
+  // Apply role-based guards
+  expressApp.use("/admin/*", AuthModule.roleGuard("admin"));
+
+  await app.bootstrap(Application);
+}
+
+bootstrap();
+```
+
+**Testing Authentication:**
+
+```bash
+# Register
+curl -X POST http://localhost:3000/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"secret123","name":"John Doe"}'
+
+# Response: {"user":{"id":1,"email":"user@example.com","name":"John Doe"},"token":"eyJ..."}
+
+# Login
+curl -X POST http://localhost:3000/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"secret123"}'
+
+# Access protected route
+curl http://localhost:3000/api/me \
+  -H "Authorization: Bearer YOUR_TOKEN_HERE"
+```
+
+---
+
+## Database Operations
+
+### Use Case 3: Advanced Database Migrations
+
+```bash
+# Create migration
+fragment migrate:create AddProductCategories
+
+# Run all pending migrations
+fragment migrate:run
+
+# Check migration status
+fragment migrate:status
+
+# Revert last migration
+fragment migrate:revert
+
+# Refresh all migrations (drop and re-run - CAREFUL!)
+fragment migrate:refresh
+
+# Sync schema (development only - not for production!)
+fragment schema:sync
+
+# Drop all tables (DANGEROUS!)
+fragment schema:drop
+```
+
+**Example Migration: src/migrations/1234567890-AddProductCategories.ts**
+
+```typescript
+import {
+  MigrationInterface,
+  QueryRunner,
+  Table,
+  TableForeignKey,
+} from "typeorm";
+
+export class AddProductCategories1234567890 implements MigrationInterface {
+  async up(queryRunner: QueryRunner): Promise<void> {
+    // Create categories table
+    await queryRunner.createTable(
+      new Table({
+        name: "category",
+        columns: [
+          {
+            name: "id",
+            type: "int",
+            isPrimary: true,
+            isGenerated: true,
+            generationStrategy: "increment",
+          },
+          { name: "name", type: "varchar", isUnique: true },
+          { name: "description", type: "text", isNullable: true },
+          {
+            name: "createdAt",
+            type: "timestamp",
+            default: "CURRENT_TIMESTAMP",
+          },
+        ],
+      }),
+    );
+
+    // Add category column to products
+    await queryRunner.query(`ALTER TABLE product ADD COLUMN categoryId INT`);
+
+    // Add foreign key
+    await queryRunner.createForeignKey(
+      "product",
+      new TableForeignKey({
+        columnNames: ["categoryId"],
+        referencedTableName: "category",
+        referencedColumnNames: ["id"],
+        onDelete: "SET NULL",
+      }),
+    );
+  }
+
+  async down(queryRunner: QueryRunner): Promise<void> {
+    // Drop foreign key first
+    const table = await queryRunner.getTable("product");
+    const foreignKey = table?.foreignKeys.find(
+      (fk) => fk.columnNames.indexOf("categoryId") !== -1,
+    );
+    if (foreignKey) {
+      await queryRunner.dropForeignKey("product", foreignKey);
+    }
+
+    // Drop column and table
+    await queryRunner.dropColumn("product", "categoryId");
+    await queryRunner.dropTable("category");
+  }
+}
+```
+
+### Database Seeding
+
+```bash
+# Create seed
+fragment seed:create InitialData
+
+# Run all seeds
+fragment seed
+```
+
+**src/seeds/InitialData.seed.ts**
+
+```typescript
+import { TypeORMModule } from "fragment";
+
+export default class InitialDataSeed {
+  static async run() {
+    const dataSource = TypeORMModule.getDataSource();
+
+    // Seed categories
+    await dataSource.query(`
+      INSERT INTO category (name, description) VALUES
+      ('Electronics', 'Electronic devices and accessories'),
+      ('Clothing', 'Apparel and fashion items'),
+      ('Books', 'Physical and digital books')
+    `);
+
+    // Seed products
+    await dataSource.query(`
+      INSERT INTO product (name, price, stock, categoryId) VALUES
+      ('Laptop', 999.99, 50, 1),
+      ('T-Shirt', 29.99, 200, 2),
+      ('Novel', 14.99, 100, 3)
+    `);
+
+    console.log("✅ Initial data seeded successfully");
+  }
+}
+```
+
+---
+
+## AI-Powered Applications
+
+### Use Case 4: AI Chat Service
+
+```bash
+# Initialize with AI feature
+fragment init ai-app --features=ai
+cd ai-app
+
+# Generate AI components
+fragment generate controller chat
+fragment generate service chat
+```
+
+**src/services/chat.service.ts**
+
+```typescript
+import { Service } from "fragment";
+import { AIModule } from "fragment";
+
+@Service()
+export class ChatService {
+  private aiModule: AIModule;
+
+  constructor() {
+    this.aiModule = new AIModule({
+      openaiKey: process.env.OPENAI_API_KEY,
+      ollamaUrl: process.env.OLLAMA_URL,
+    });
+  }
+
+  async chat(message: string, history: any[] = []) {
+    const messages = [
+      { role: "system" as const, content: "You are a helpful assistant." },
+      ...history,
+      { role: "user" as const, content: message },
+    ];
+
+    const response = await this.aiModule.complete(messages, {
+      model: "gpt-3.5-turbo",
+      temperature: 0.7,
+      maxTokens: 500,
+    });
+
+    return {
+      response,
+      history: [
+        ...history,
+        { role: "user", content: message },
+        { role: "assistant", content: response },
+      ],
+    };
+  }
+
+  async streamChat(message: string, onChunk: (chunk: string) => void) {
+    const messages = [
+      { role: "system" as const, content: "You are a helpful assistant." },
+      { role: "user" as const, content: message },
+    ];
+
+    await this.aiModule.streamComplete(
+      messages,
+      { model: "gpt-3.5-turbo" },
+      onChunk,
+    );
+  }
+
+  async generateEmbeddings(texts: string[]) {
+    return this.aiModule.embeddings(texts);
+  }
+}
+```
+
+**src/controllers/chat.controller.ts**
+
+```typescript
+import { Controller, Post, Body, Res } from "fragment";
+import { ChatService } from "../services/chat.service";
+import { Response } from "express";
+
+@Controller("/chat")
+export class ChatController {
+  constructor(private chatService: ChatService) {}
+
+  @Post("/message")
+  async sendMessage(@Body() body: any) {
+    return this.chatService.chat(body.message, body.history || []);
+  }
+
+  @Post("/stream")
+  async streamMessage(@Body() body: any, @Res() res: Response) {
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+
+    await this.chatService.streamChat(body.message, (chunk) => {
+      res.write(`data: ${JSON.stringify({ chunk })}\n\n`);
+    });
+
+    res.write("data: [DONE]\n\n");
+    res.end();
+  }
+
+  @Post("/embeddings")
+  async getEmbeddings(@Body() body: any) {
+    const embeddings = await this.chatService.generateEmbeddings(body.texts);
+    return { embeddings };
+  }
+}
+```
+
+**.env Configuration:**
+
+```env
+NODE_ENV=development
+PORT=3000
+OPENAI_API_KEY=sk-your-key-here
+OLLAMA_URL=http://localhost:11434
+```
+
+**Testing AI Endpoints:**
+
+```bash
+# Chat
+curl -X POST http://localhost:3000/chat/message \
+  -H "Content-Type: application/json" \
+  -d '{"message":"What is TypeScript?"}'
+
+# Stream (watch responses appear in real-time)
+curl -X POST http://localhost:3000/chat/stream \
+  -H "Content-Type: application/json" \
+  -d '{"message":"Write a short story"}' \
+  --no-buffer
+
+# Embeddings (vector representations of text)
+curl -X POST http://localhost:3000/chat/embeddings \
+  -H "Content-Type: application/json" \
+  -d '{"texts":["Hello world","Fragment Framework"]}'
+```
+
+---
+
+## Dependency Injection Patterns
+
+### Use Case 5: Complex DI with Multiple Services
+
+```typescript
+// src/services/email.service.ts
+import { Service } from "fragment";
+
+@Service()
+export class EmailService {
+  async sendEmail(to: string, subject: string, body: string) {
+    console.log(`Sending email to ${to}: ${subject}`);
+    // Email sending logic (SendGrid, Mailgun, etc.)
+    return { sent: true };
+  }
+}
+
+// src/services/notification.service.ts
+import { Service, Autowired } from "fragment";
+import { EmailService } from "./email.service";
+
+@Service()
+export class NotificationService {
+  // Property injection using @Autowired
+  @Autowired()
+  private emailService: EmailService;
+
+  async notifyUser(userId: string, message: string) {
+    // Send email notification
+    await this.emailService.sendEmail(
+      `user${userId}@example.com`,
+      "Notification",
+      message,
+    );
+  }
+}
+
+// src/services/order.service.ts
+import { Service } from "fragment";
+import { NotificationService } from "./notification.service";
+import { ProductRepository } from "../repositories/product.repository";
+
+@Service()
+export class OrderService {
+  // Constructor injection
+  constructor(
+    private notificationService: NotificationService,
+    private productRepository: ProductRepository,
+  ) {}
+
+  async createOrder(userId: string, productId: number, quantity: number) {
+    const product = await this.productRepository.findById(productId);
+
+    if (!product || product.stock < quantity) {
+      throw new Error("Insufficient stock");
+    }
+
+    // Update stock
+    await this.productRepository.update(productId, {
+      stock: product.stock - quantity,
+    });
+
+    // Notify user
+    await this.notificationService.notifyUser(
+      userId,
+      `Your order for ${quantity}x ${product.name} has been placed!`,
+    );
+
+    return { orderId: Date.now(), product, quantity };
+  }
+}
+```
+
+---
+
+## Advanced Routing
+
+### Use Case 6: Complex Route Parameters
+
+```typescript
+import {
+  Controller,
+  Get,
+  Post,
+  Param,
+  Query,
+  Header,
+  Body,
+  Req,
+  Res,
+} from "fragment";
+import { Request, Response } from "express";
+
+@Controller("/api/v1/users")
+export class UserController {
+  // Nested route parameters
+  // Route: GET /api/v1/users/:userId/orders/:orderId
+  @Get("/:userId/orders/:orderId")
+  async getUserOrder(
+    @Param("userId") userId: string,
+    @Param("orderId") orderId: string,
+  ) {
+    return { userId, orderId };
+  }
+
+  // Query parameters
+  // Route: GET /api/v1/users?page=1&limit=10&sort=name
+  @Get()
+  async getUsers(
+    @Query("page") page: string,
+    @Query("limit") limit: string,
+    @Query("sort") sort: string,
+  ) {
+    return {
+      page: parseInt(page) || 1,
+      limit: parseInt(limit) || 10,
+      sort: sort || "id",
+      users: [],
+    };
+  }
+
+  // Header extraction
+  @Get("/profile")
+  async getProfile(@Header("Authorization") auth: string) {
+    return { authorized: !!auth };
+  }
+
+  // Complex body handling
+  @Post("/bulk")
+  async bulkCreate(@Body() body: any) {
+    const users = body.users || [];
+    return { created: users.length };
+  }
+
+  // Full request/response access
+  @Get("/advanced")
+  async advancedRoute(@Req() req: Request, @Res() res: Response) {
+    res.status(200).json({
+      method: req.method,
+      path: req.path,
+      headers: req.headers,
+    });
+  }
+}
+```
+
+---
+
+## Custom Middleware
+
+### Use Case 7: Request Logging Middleware
+
+```typescript
+// src/middlewares/logger.middleware.ts
+import { Request, Response, NextFunction } from "express";
+
+export class LoggerMiddleware {
+  use(req: Request, res: Response, next: NextFunction) {
+    const start = Date.now();
+
+    res.on("finish", () => {
+      const duration = Date.now() - start;
+      console.log(
+        `${req.method} ${req.path} - ${res.statusCode} - ${duration}ms`,
+      );
+    });
+
+    next();
+  }
+}
+
+// src/main.ts
+import "reflect-metadata";
+import { FragmentApplication, FragmentWebApplication } from "fragment";
+import { LoggerMiddleware } from "./middlewares/logger.middleware";
+
+@FragmentApplication({
+  port: 3000,
+  autoScan: true,
+})
+class Application {}
+
+async function bootstrap() {
+  const app = new FragmentWebApplication();
+  const expressApp = app.getExpressApp();
+
+  // Apply middleware
+  const logger = new LoggerMiddleware();
+  expressApp.use(logger.use.bind(logger));
+
+  await app.bootstrap(Application);
+}
+
+bootstrap();
+```
+
+---
+
+## Testing
+
+### Use Case 8: Comprehensive Testing
+
+```bash
+# Generate test file alongside controller
+fragment generate controller users
+```
+
+**test/users.spec.ts**
+
+```typescript
+import { describe, it, expect } from "fragment";
+import { DIContainer } from "fragment";
+import { UserService } from "../src/services/user.service";
+
+describe("UserService", () => {
+  let userService: UserService;
+
+  beforeEach(() => {
+    const container = DIContainer.getInstance();
+    userService = container.resolve<UserService>(UserService);
+  });
+
+  it("should create a user", async () => {
+    const user = await userService.create({
+      email: "test@example.com",
+      name: "Test User",
+      password: "password123",
+    });
+
+    expect(user).toBeTruthy();
+    expect(user.email).toBe("test@example.com");
+    expect(user.name).toBe("Test User");
+  });
+
+  it("should find user by id", async () => {
+    const user = await userService.findOne("1");
+    expect(user).toBeTruthy();
+    expect(user.id).toBe(1);
+  });
+
+  it("should throw error for non-existent user", async () => {
+    expect(() => userService.findOne("99999")).toThrow();
+  });
+
+  it("should update user", async () => {
+    const updated = await userService.update("1", { name: "Updated Name" });
+    expect(updated.name).toBe("Updated Name");
+  });
+});
+```
+
+```bash
+# Run tests
+fragment test
+
+# Run with coverage
+fragment test --coverage
+
+# Run specific test file
+fragment test test/users.spec.ts
+```
+
+---
+
+## Production Deployment
+
+### Use Case 9: Deploy to Production
+
+**Build and Deploy**
+
+```bash
+# Build for production
+fragment build
+
+# Verify build
+ls dist/
+
+# Set production environment variables
+export NODE_ENV=production
+export PORT=8080
+export DATABASE_URL=postgresql://user:pass@host:5432/db
+export JWT_SECRET=super-secret-production-key
+
+# Run migrations
+fragment migrate:run
+
+# Start production server
+npm start
+```
+
+**Docker Deployment**
+
+**Dockerfile:**
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install production dependencies
+RUN npm ci --only=production
+
+# Copy source code
+COPY . .
+
+# Build TypeScript
+RUN npm run build
+
+# Expose port
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s \
+  CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
+
+# Start application
+CMD ["npm", "start"]
+```
+
+**docker-compose.yml:**
+
+```yaml
+version: "3.8"
+
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
+      - JWT_SECRET=your-secret-key
+    depends_on:
+      - db
+    restart: unless-stopped
+
+  db:
+    image: postgres:15-alpine
+    environment:
+      - POSTGRES_DB=myapp
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=password
+    volumes:
+      - db-data:/var/lib/postgresql/data
+    restart: unless-stopped
+
+volumes:
+  db-data:
+```
+
+```bash
+# Build and start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f app
+
+# Run migrations in container
+docker-compose exec app fragment migrate:run
+
+# Stop services
+docker-compose down
+
+# Stop and remove volumes
+docker-compose down -v
+```
+
+---
+
+## CLI Reference
+
+### Complete CLI Command Reference
+
+**Project Management**
+
+```bash
+fragment init [dir]              # Initialize new project
+fragment init . --features=auth  # Initialize with features in current dir
+fragment serve                   # Start development server
+fragment serve --port=4000       # Start on custom port
+fragment serve --no-watch        # Disable hot reload
+fragment build                   # Build for production
+```
+
+**Code Generation**
+
+```bash
+fragment generate <type> <name>  # Generate component
+fragment g <type> <name>         # Shorthand
+
+# Types:
+fragment generate controller users
+fragment generate service auth
+fragment generate entity product
+fragment generate repository users
+fragment generate dto create-user
+fragment generate resource product  # Generates all of the above
+
+# With options:
+fragment generate service users --with-repository
+```
+
+**Database Operations**
+
+```bash
+fragment migrate                 # Run pending migrations
+fragment migrate:create <name>   # Create new migration
+fragment migrate:run             # Run migrations
+fragment migrate:revert          # Revert last migration
+fragment migrate:refresh         # Drop and re-run all migrations
+fragment migrate:status          # Show migration status
+fragment schema:sync             # Sync schema (dev only)
+fragment schema:drop             # Drop all tables
+fragment seed                    # Run seeds
+fragment seed:create <name>      # Create seed file
+```
+
+**Diagnostics**
+
+```bash
+fragment routes                  # List all routes (auto-detect mode)
+fragment routes --env=dev        # List routes from TypeScript src/
+fragment routes --env=prod       # List routes from compiled dist/
+fragment beans                   # List all beans
+fragment beans --tree            # Show beans as tree
+fragment info                    # Show app information
+fragment config                  # Show configuration
+fragment version                 # Show Fragment version
+```
+
+### Diagnostics & Debugging
+
+**Environment-Specific Diagnostics**
+
+```bash
+# Auto-detect (prefers src/ if available, falls back to dist/)
+fragment routes
+fragment beans
+
+# Force development mode (use TypeScript source)
+fragment routes --env=dev
+fragment beans --env=dev --tree
+
+# Force production mode (use compiled JavaScript)
+fragment routes --env=prod
+fragment beans --env=prod
+
+# Show application info
+fragment info
+# Output:
+# 📊 Application Information:
+#   Name:        my-app
+#   Version:     1.0.0
+#   Node:        v18.17.0
+#   Platform:    darwin
+#   Architecture: arm64
+#   Environment: development
+#   Source:      ✓ src/
+#   Built:       ✓ dist/
+
+# View configuration
+fragment config
+# Shows contents of fragment.json
+
+# Check version
+fragment version
+# ✨ Fragment Framework v1.0.0
+```
+
+---
+
+## Best Practices
+
+### Development
+
+1. **Always use decorators** - Leverage `@Controller`, `@Service`, `@Injectable` for clean architecture
+2. **Keep services focused** - One responsibility per service (Single Responsibility Principle)
+3. **Use DTOs** - Define Data Transfer Objects for request/response validation
+4. **Type everything** - Take advantage of TypeScript's type system
+5. **Use environment variables** - Never hardcode secrets or configuration
+
+### Database
+
+1. **Use migrations in production** - Never use `synchronize: true` in production
+2. **Version your migrations** - Keep migration files in version control
+3. **Test migrations** - Always test both `up` and `down` migrations
+4. **Use transactions** - Wrap related operations in database transactions
+5. **Index strategically** - Add indexes for frequently queried columns
+
+### Security
+
+1. **Hash passwords** - Always use `AuthModule.hashPassword()`
+2. **Validate input** - Use DTOs with class-validator
+3. **Rate limiting** - Implement rate limiting on public endpoints
+4. **CORS configuration** - Configure CORS appropriately for your frontend
+5. **Environment-specific secrets** - Use different secrets for dev/prod
+
+### Testing
+
+1. **Test business logic** - Focus on service and repository tests
+2. **Mock external dependencies** - Don't hit real databases or APIs in tests
+3. **Test edge cases** - Test error conditions and boundary cases
+4. **Use descriptive test names** - Make test failures easy to understand
+
+### Deployment
+
+1. **Use Docker** - Containerize your application for consistent deployments
+2. **Health checks** - Implement health check endpoints
+3. **Logging** - Use structured logging for production
+4. **Monitoring** - Set up monitoring and alerting
+5. **Backup strategy** - Regular database backups
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### Issue: "Cannot find module"
+
+```bash
+# Solution: Rebuild the project
+npm run build
+fragment serve
+```
+
+#### Issue: "Port already in use"
+
+```bash
+# Solution 1: Use different port
+fragment serve --port=4000
+
+# Solution 2: Kill process using port (macOS/Linux)
+lsof -ti:3000 | xargs kill -9
+
+# Solution 3: Kill process using port (Windows)
+netstat -ano | findstr :3000
+taskkill /PID <PID> /F
+```
+
+#### Issue: "Database connection failed"
+
+```bash
+# Check configuration
+fragment config
+
+# Test connection
+fragment migrate:status
+
+# Verify DATABASE_URL
+echo $DATABASE_URL
+
+# Common fixes:
+# - Ensure database server is running
+# - Check username/password
+# - Verify database name exists
+# - Check network connectivity
+```
+
+#### Issue: "Decorators not working"
+
+```bash
+# Ensure tsconfig.json has these settings:
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+
+# Rebuild after changes
+npm run build
+```
+
+#### Issue: "Routes not registering"
+
+```bash
+# Check if components are being scanned
+fragment routes
+
+# If no routes shown:
+# 1. Ensure files follow naming convention (*.controller.ts)
+# 2. Verify decorators are applied correctly
+# 3. Check if autoScan is enabled in @FragmentApplication
+# 4. Try manual import in main.ts
+
+# Force specific environment
+fragment routes --env=dev
+fragment routes --env=prod
+```
+
+#### Issue: "Circular dependency detected"
+
+```bash
+# Error: Circular dependency detected: UserService
+
+# Solution: Use property injection instead of constructor injection
+# Before (circular):
+@Service()
+class UserService {
+  constructor(private authService: AuthService) {}
+}
+@Service()
+class AuthService {
+  constructor(private userService: UserService) {} // Circular!
+}
+
+# After (fixed):
+@Service()
+class UserService {
+  @Autowired()
+  private authService: AuthService; // Property injection breaks cycle
+}
+```
+
+#### Issue: "Hot reload not working"
+
+```bash
+# Check if chokidar is installed
+npm install --save-dev chokidar
+
+# Restart with watch mode explicitly enabled
+fragment serve --watch
+
+# Check file watch patterns in serve command
+```
+
+#### Issue: "Migration fails"
+
+```bash
+# Revert last migration
+fragment migrate:revert
+
+# Check migration status
+fragment migrate:status
+
+# Fix migration file and re-run
+fragment migrate:run
+
+# If all else fails, drop and recreate (DEV ONLY!)
+fragment schema:drop
+fragment migrate:run
+```
+
+#### Issue: "TypeScript compilation errors"
+
+```bash
+# Check TypeScript version compatibility
+npm list typescript
+
+# Clear build artifacts
+rm -rf dist/
+npm run build
+
+# Check for conflicting type definitions
+npm list @types
+```
+
+---
+
+## Performance Tips
+
+### Optimize Database Queries
+
+```typescript
+// Use eager loading to avoid N+1 queries
+const users = await userRepository.find({
+  relations: ["posts", "comments"],
+});
+
+// Use indexes for frequently queried columns
+@Entity()
+export class User {
+  @Index()
+  @Column({ unique: true })
+  email: string;
+}
+
+// Use pagination for large datasets
+const [users, total] = await userRepository.findAndCount({
+  skip: (page - 1) * limit,
+  take: limit,
+});
+```
+
+### Caching Strategies
+
+```typescript
+// In-memory cache for frequently accessed data
+@Service()
+export class CacheService {
+  private cache = new Map<string, any>();
+
+  get(key: string) {
+    return this.cache.get(key);
+  }
+
+  set(key: string, value: any, ttl: number = 3600000) {
+    this.cache.set(key, value);
+    setTimeout(() => this.cache.delete(key), ttl);
+  }
+}
+```
+
+### Connection Pooling
+
+```json
+// fragment.json
+{
+  "database": {
+    "poolSize": 10,
+    "maxQueryExecutionTime": 1000
+  }
+}
+```
+
+---
+
+## Summary
+
+Fragment Framework provides:
+
+- ✅ **Quick project initialization** - `fragment init .` or `fragment init my-app`
+- ✅ **Hot reload development** - Automatic server restart on file changes
+- ✅ **Comprehensive CLI** - Code generation, migrations, diagnostics
+- ✅ **Built-in authentication** - JWT, password hashing, role guards
+- ✅ **Database migrations** - TypeORM integration with full migration support
+- ✅ **AI integrations** - OpenAI, Ollama, and custom providers
+- ✅ **Production-ready** - Docker, health checks, logging
+- ✅ **Type-safe DI** - Automatic dependency injection
+- ✅ **Convention over configuration** - Sensible defaults, minimal setup
+- ✅ **Environment flexibility** - Dev/prod modes with `--env` flag
+
+**Start building your next TypeScript application with Fragment today!**
+
+```bash
+npm install -g fragment
+fragment init my-app
+cd my-app
+fragment serve
+```
+
+Visit [https://fragment.digitwhale.com](https://fragment.digitwhale.com) for more documentation and examples.