TaskMaster - Task Management System

TaskMaster - Complete Task Management System

TaskMaster is a comprehensive backend example that demonstrates the full capabilities of Veloce-TS. This example showcases how to build a production-ready task management system with authentication, authorization, real-time features, and more.

:::tip Current releases This walkthrough targets Veloce-TS v0.4.x on npm. Cross-check imports and plugin APIs with the changelog—older snippets in this page may predate VeloceTS, usePlugin, or RFC 9457 errors. :::

:::note Basic Example This is a basic backend-only example designed to demonstrate Veloce-TS capabilities. It focuses on API development and doesn’t include a frontend interface. :::

🚀 Features Demonstrated

✅ Core Framework Features

• Decorator-based routing (@Controller, @Get, @Post, etc.)
• Dependency Injection with singleton scope
• Request validation using Zod schemas
• Automatic OpenAPI documentation
• Custom middleware (logging, analytics, performance)
• Error handling with custom exceptions
• Plugin system integration

✅ Authentication & Authorization

• JWT-based authentication with access/refresh tokens
• Role-Based Access Control (RBAC) with 5 role levels
• Granular permissions system
• Protected routes and endpoints

✅ Database & Persistence

• SQLite integration using Bun’s native database
• CRUD operations for all entities
• Data validation and type safety
• Relationship management

✅ Advanced Features

• GraphQL support with custom resolvers
• WebSocket handlers for real-time notifications
• Analytics middleware for performance tracking
• Admin panel endpoints for system management

📁 Project Structure

taskmaster/
├── src/
│   ├── controllers/          # REST API controllers
│   │   ├── auth.controller.ts
│   │   ├── task.controller.ts
│   │   ├── user.controller.ts
│   │   ├── team.controller.ts
│   │   └── admin.controller.ts
│   ├── services/             # Business logic services
│   │   ├── user.service.ts
│   │   ├── task.service.ts
│   │   ├── team.service.ts
│   │   └── notification.service.ts
│   ├── resolvers/            # GraphQL resolvers
│   │   ├── task.resolver.ts
│   │   └── user.resolver.ts
│   ├── websockets/           # WebSocket handlers
│   │   └── notification.websocket.ts
│   ├── middleware/           # Custom middleware
│   │   ├── logging.middleware.ts
│   │   └── analytics.middleware.ts
│   ├── models/               # TypeScript types
│   │   └── types.ts
│   ├── config/               # Configuration files
│   │   ├── auth.config.ts
│   │   └── database.ts
│   └── index.ts              # Application entry point
├── package.json
└── README.md

🛠️ Setup & Installation

Prerequisites

• Bun >= 1.0.0
• Node.js >= 18.0.0

Quick Start

1. Clone the example:

git clone <repository-url>
cd examples/veloce-taskmaster

2. Install dependencies:

bun install

3. Run the development server:

bun run dev

4. Access the API:

• API Documentation: http://localhost:3001/docs
• Health Check: http://localhost:3001/health
• API Info: http://localhost:3001/api

📚 Key Implementation Examples

🔐 Authentication Controller

@Controller('/api/auth')
export class AuthController {
  @Post('/login')
  @ApiDoc({ summary: 'User login' })
  async login(
    @Body(LoginSchema) credentials: LoginCredentials,
    @Depends(UserService) userService: UserService,
    @Depends(AuthService) authService: AuthService
  ) {
    const user = await userService.validateCredentials(
      credentials.username,
      credentials.password
    );

    if (!user) {
      throw new AuthenticationException('Invalid credentials');
    }

    const tokens = await authService.generateTokens({
      sub: user.id,
      username: user.username,
      role: user.role,
      permissions: user.permissions
    });

    return { user, tokens };
  }
}

🎯 Task Controller with RBAC

@Controller('/api/tasks')
export class TaskController {
  @Get('/')
  @Auth()
  @MinimumRole('developer')
  async listTasks(
    @Query() filters: TaskFilters,
    @CurrentUser() user: JWTPayload,
    @Depends(TaskService) taskService: TaskService
  ) {
    // Role-based filtering
    if (user.role !== 'admin' && user.role !== 'manager') {
      filters.assigneeId = user.sub;
    }

    return await taskService.findAll(filters);
  }

  @Post('/')
  @Auth()
  @MinimumRole('developer')
  @Permissions(['tasks:create'])
  async createTask(
    @Body(CreateTaskSchema) data: CreateTaskDTO,
    @CurrentUser() user: JWTPayload,
    @Depends(TaskService) taskService: TaskService
  ) {
    return await taskService.create(data, user.sub);
  }
}

🗄️ Service Layer with SQLite

export class TaskService {
  private db: Database;

  constructor() {
    this.db = getDatabase();
  }

  async create(data: CreateTaskDTO, creatorId: string): Promise<Task> {
    const stmt = this.db.prepare(`
      INSERT INTO tasks (title, description, priority, creator_id, status)
      VALUES (?, ?, ?, ?, ?)
    `);

    const result = stmt.run(
      data.title,
      data.description,
      data.priority,
      creatorId,
      'todo'
    );

    return await this.findById(result.lastInsertRowid.toString());
  }
}

📊 GraphQL Resolver

@Resolver('Task')
export class TaskResolver {
  @GQLQuery('tasks')
  @Arg('filters', () => TaskFiltersInput)
  async getTasks(
    @Arg('filters') filters: TaskFilters,
    @Depends(TaskService) taskService: TaskService
  ) {
    return await taskService.findAll(filters);
  }

  @GQLMutation('createTask')
  @Arg('input', () => CreateTaskInput)
  async createTask(
    @Arg('input') input: CreateTaskDTO,
    @Depends(TaskService) taskService: TaskService,
    @CurrentUser() user: JWTPayload
  ) {
    return await taskService.create(input, user.sub);
  }
}

🔌 WebSocket Handler

@WebSocket('/ws/notifications')
export class NotificationWebSocket {
  @OnConnect()
  async onConnect(connection: WebSocketConnection) {
    console.log('User connected:', connection.id);
  }

  @OnMessage()
  async onMessage(
    connection: WebSocketConnection,
    message: any
  ) {
    // Broadcast notification to all connected clients
    await this.broadcast(message);
  }
}

🛡️ Custom Middleware

export const loggingMiddleware = async (c: Context, next: Next) => {
  const start = Date.now();
  const requestId = crypto.randomUUID();

  c.set('requestId', requestId);
  c.set('startTime', start);

  console.log(`[${requestId}] → ${c.req.method} ${c.req.url}`);

  await next();

  const duration = Date.now() - start;
  console.log(`[${requestId}] ← ${c.req.method} ${c.req.url} ${c.res.status} (${duration}ms)`);
};

🎮 Demo Users

The example includes pre-configured demo users for testing:

Username	Password	Role	Permissions
admin	admin123	admin	Full access
manager1	manager123	manager	Team management
teamlead1	lead123	team_lead	Project leadership
dev1	dev123	developer	Task management
dev2	dev123	developer	Task management

📡 API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• POST /api/auth/refresh - Token refresh
• GET /api/auth/me - Get current user

Tasks

• GET /api/tasks - List tasks (with filtering)
• GET /api/tasks/:id - Get task by ID
• POST /api/tasks - Create new task
• PUT /api/tasks/:id - Update task
• DELETE /api/tasks/:id - Delete task
• POST /api/tasks/:id/status - Update task status
• POST /api/tasks/:id/assign - Assign task
• GET /api/tasks/stats/overview - Task statistics

Users & Teams

• GET /api/users - List users
• GET /api/teams - List teams
• POST /api/teams - Create team
• POST /api/teams/:id/members - Add team member

Admin (Admin only)

• GET /api/admin/users - All users
• GET /api/admin/tasks - All tasks
• PUT /api/admin/users/:id/role - Change user role
• GET /api/admin/stats/system - System statistics

🔧 Configuration

Environment Variables

# Server Configuration
PORT=3001
NODE_ENV=development

# Database
DATABASE_URL=./taskmaster.db

# JWT Configuration
JWT_SECRET=your-super-secret-key
JWT_EXPIRES_IN=1h
JWT_REFRESH_EXPIRES_IN=7d

Database Schema

The example automatically creates the following tables:

• users - User accounts and profiles
• tasks - Task management
• teams - Team organization
• notifications - Real-time notifications

🚀 Production Considerations

While this is a basic example, here are considerations for production use:

🔒 Security

• Use environment variables for secrets
• Implement proper password hashing (bcrypt)
• Add rate limiting
• Enable HTTPS
• Configure CORS properly

🗄️ Database

• Use PostgreSQL or MySQL for production
• Implement database migrations
• Add connection pooling
• Set up database backups

📊 Monitoring

• Add comprehensive logging
• Implement health checks
• Set up error tracking
• Monitor performance metrics

🔄 Scaling

• Use Redis for session storage
• Implement horizontal scaling
• Add load balancing
• Set up CDN for static assets

📖 Learning Path

This example demonstrates:

1. Basic Setup - Project structure and configuration
2. Authentication - JWT and RBAC implementation
3. CRUD Operations - Database interactions
4. Middleware - Custom request/response handling
5. GraphQL - Alternative API approach
6. WebSockets - Real-time features
7. Validation - Request data validation
8. Documentation - OpenAPI/Swagger integration

🔗 Related Resources

• Getting Started Guide
• Decorators Documentation
• Dependency Injection
• Plugins System
• API Reference

---

:::tip Next Steps Ready to build your own application? Check out the Getting Started Guide to create your first Veloce-TS project! :::