Bun + TypeScript + Elysia Template 🚀

Clean Architecture template for high-performance web applications

Built with Bun, TypeScript, Elysia & Clean Architecture

Ready-to-use template by Gesttione Solutions ⚡️

---

🔎 Visão Rápida

Componente	Propósito	Status
Domain Layer	Business logic, entities, value objects	✅ Implementado
Application Layer	Use cases, DTOs, orchestration	✅ Implementado
Infrastructure Layer	Repositories, external services	✅ Implementado
Presentation Layer	HTTP routes, controllers, middleware	✅ Implementado
Testing Suite	Unit, integration, e2e tests	✅ Implementado

---

⚡️ Início Rápido (1 minuto)

# 1. Clonar e instalar
git clone <repo-url> && cd template-elysia && bun install

# 2. Executar aplicação
bun run dev

# 3. Verificar quality gates
bun run genex && bun run lint && bun run type-check && bun run test

Verificar:

• Aplicação: Rodando sem erros
• Testes: 25+ tests passing
• Quality Gates: ✅ All passed

---

🤖 Claude Code Integration

Este projeto possui comandos personalizados para Claude Code que otimizam o workflow de desenvolvimento:

🎯 Comandos Principais

/dev                 # TaskMaster-driven development
/qa                  # Quality gates validation
/commit-flow         # Organized commit process
/pr-create           # Automated PR creation with push

🔧 Comandos Especializados

/new-feature         # Manual feature development guide
/refactor            # Safe refactoring process
/test-focus          # Targeted testing strategies
/arch-check          # Architecture compliance analysis
/debug-help          # Troubleshooting assistant

Setup inicial:

# Os comandos estão em .claude/commands/
# Use diretamente no Claude Code: /dev, /qa, etc.

---

🚀 Workflow de Desenvolvimento

Abordagem Clean Architecture

graph LR
    A[Domain] --> B[Application]
    B --> C[Infrastructure]
    C --> D[Presentation]
    D --> E[Quality Gates]

Loading

Fluxo Típico de Feature

# 1. Desenvolvimento com TaskMaster
/dev                 # Escolher task e implementar

# 2. Validação contínua
/qa                  # Quality gates completos

# 3. Commit organizado
/commit-flow         # Estruturar e commitar

# 4. Pull Request
/pr-create           # Push e criar PR automaticamente

Quality Gates Integrados

# Sequência completa (uso do comando /qa)
bun run genex && bun run lint && bun run type-check && bun run test

# Comandos individuais
bun run genex        # Generate/update index files
bun run lint         # Biome linting and formatting
bun run type-check   # TypeScript validation
bun run test         # Vitest test suite (25+ tests)

---

🏗️ Arquitetura & Stack

Clean Architecture Layers

Camada	Responsabilidade	Tecnologias
Domain	Business logic, entities, value objects	TypeScript puro
Application	Use cases, DTOs, orchestration	TypeScript
Infrastructure	Repositories, external services	Bun, implementações
Presentation	HTTP routes, controllers	Elysia framework

Stack Tecnológica

Categoria	Tecnologias
Runtime	Bun (fast JavaScript runtime)
Language	TypeScript (strict mode)
Framework	Elysia (fast & type-safe web framework)
Testing	Vitest (NOT Bun's test runner)
Code Quality	Biome (linting + formatting)
Git Hooks	Husky + lint-staged
Architecture	Clean Architecture + SOLID principles

---

📂 Estrutura do Projeto

src/
├── domain/
│   ├── entities/           # Business objects (User)
│   ├── value-objects/      # Immutable primitives (Email, UserId)
│   ├── ports/             # Interfaces (UserRepository)
│   └── services/          # Domain business logic
├── application/
│   ├── use-cases/         # Application business rules
│   ├── dtos/              # Data transfer objects
│   ├── ports/             # Application interfaces
│   └── services/          # Application orchestration
├── infrastructure/
│   ├── controllers/       # HTTP request handlers
│   ├── persistence/       # Data access implementations
│   └── http/              # HTTP configurations
└── presentation/
    ├── routes/            # HTTP route definitions
    ├── middleware/        # Request/response middleware
    └── controllers/       # Presentation controllers

tests/
└── unit/
    ├── domain/            # Domain layer tests
    ├── application/       # Application layer tests
    └── infrastructure/    # Infrastructure tests

utils/
└── genex/                 # Index file generator
    ├── processors/        # Generation strategies
    ├── types.ts          # Type definitions
    └── utils.ts          # Utility functions

.claude/
└── commands/              # Claude Code custom commands
    ├── dev.md            # TaskMaster development
    ├── qa.md             # Quality gates
    ├── commit-flow.md    # Commit organization
    └── pr-create.md      # PR automation

---

🧪 Testing & Quality

Test Architecture

• Unit Tests: Domain and Application logic (25+ tests implemented)
• Test Structure: Mirrors src/ directory structure
• Coverage: Comprehensive coverage for business logic
• Framework: Vitest with strict TypeScript

Quality Standards

# Complete quality check
/qa                      # Use Claude Code command

# Individual validations
bun run genex           # ✅ Index files updated
bun run lint            # ✅ Biome formatting applied
bun run type-check      # ✅ TypeScript strict compliance
bun run test            # ✅ All tests passing (25+)

Pre-commit Hooks

Automated quality gates via Husky:

1. Branch protection - Prevents commits to protected branches
2. Lint-staged - Auto-formatting with Biome
3. Type checking - TypeScript validation
4. Unit tests - Complete test suite execution
5. Architecture analysis - Clean Architecture compliance
6. Index generation - Auto-update exports

---

🎯 Development Philosophy

Pragmatism over Purism

"Functionality first, perfect architecture second. Apply Clean Architecture and DDD patterns where they add clear value, not everywhere."

Key Principles

1. Small commits with comprehensive quality gates
2. Delete unused variables instead of using _ prefix
3. Functionality over perfect architecture
4. Clean separation of concerns where it adds value
5. Quality gates as foundation of development workflow

Git Workflow

# 🚨 RULE: Never work on protected branches
git checkout -b feat/feature-description

# Development cycle
/dev                    # Implement with TaskMaster guidance
/qa                     # Validate quality gates
/commit-flow            # Organize and commit
/pr-create              # Push and create PR

# Protected branches: main, master, develop, staging, production

---

🔧 Scripts de Desenvolvimento

# Desenvolvimento
bun run dev             # Start development server with watch
bun run build           # Build for production
bun run start           # Run built application

# Quality & Testing (Use Vitest, NOT Bun's test runner)
bun run test            # Run all tests (uses Vitest)
bun run test:watch      # Tests in watch mode
bun run test:coverage   # Tests with coverage report
bun run test:ui         # Vitest UI for interactive testing

# Code Quality
bun run genex           # Generate index.ts files automatically
bun run lint            # Biome linter and formatter (auto-fixes)
bun run type-check      # TypeScript type checking

# Quality Gates Sequence
bun run genex && bun run lint && bun run type-check && bun run test

# Utilities
bun run clean           # Clean build artifacts
bun install             # Install dependencies

---

🚨 Troubleshooting Rápido

Problema	Solução
Tests not exiting	Use bun run test (not bun test)
TypeScript errors	Run bun run genex to update index files
Linting issues	Run bun run lint for auto-fix
Import/export errors	Check if files follow naming conventions
Architecture violations	Use /arch-check command for analysis
Pre-commit hook fails	Run /qa to identify and fix issues
Protected branch error	Create feature branch: git checkout -b
Build failures	Run bun install && bun run type-check

Para debugging detalhado: Use o comando /debug-help no Claude Code

---

📋 Convenções

Naming Conventions

# Files: kebab-case.type.extension
user.entity.ts
email.vo.ts
create-user.use-case.ts
user.controller.ts

# Classes: PascalCase
export class User {}
export class Email {}
export class CreateUserUseCase {}

Module Resolution

// Path aliases configured
import { User } from '@/domain/entities'
import { CreateUserUseCase } from '@/application/use-cases'

// Auto-generated exports via genex
export * from './entities'
export * from './value-objects'
export * from './ports'

Commit Messages

# Conventional commits
feat(domain): add User entity with email validation
fix(tests): resolve async test timing issues
refactor(infrastructure): extract common repository patterns
docs: update development workflow documentation

---

🎯 Development Patterns

Value Object Creation

export class Email {
  private constructor(private readonly value: string) {}
  
  static create(value: string): Email {
    // Validation logic
    return new Email(value);
  }
  
  equals(other: Email): boolean {
    return this.value === other.value;
  }
}

Use Case Pattern

export class CreateUserUseCase {
  constructor(private userRepository: UserRepository) {}
  
  async execute(input: CreateUserInput): Promise<CreateUserOutput> {
    // Application logic
  }
}

Repository Implementation

export class InMemoryUserRepository implements UserRepository {
  async save(user: User): Promise<void> {
    // Implementation
  }
}

---

📈 Métricas & Status

Current Status

• Domain Layer: ✅ Complete (User entity, Email/UserId VOs)
• Application Layer: ✅ Complete (CreateUser/GetUser use cases)
• Infrastructure Layer: ✅ Basic implementation (InMemory repository)
• Testing: ✅ 25+ tests passing (100% domain coverage)
• Quality Gates: ✅ All automated and passing

Architecture Compliance

• ✅ Clean Architecture layers respected
• ✅ Domain layer has zero external dependencies
• ✅ Dependency inversion properly implemented
• ✅ Repository pattern for data access
• ✅ Value objects for domain primitives

---

🆕 Features

Index File Generation (Genex)

• Automatic index.ts file generation
• Configurable via genex.json
• Modular processor architecture
• Clean exports for each layer

Quality Automation

• Pre-commit hooks with comprehensive checks
• Real-time quality validation
• Architecture compliance analysis
• Automated code formatting

Claude Code Integration

• Custom development commands
• TaskMaster AI integration
• Workflow automation
• Context-aware assistance

---

🔒 Direitos Autorais

Projeto desenvolvido seguindo Clean Architecture e SOLID principles.

---

Bun + TypeScript + Elysia Template – High-performance web applications with Clean Architecture Built by Gesttione Solutions with modern development practices 🚀