create-fluxstack 1.0.1 → 1.0.3

package/ai-context/project/architecture.md

@@ -0,0 +1,399 @@
+# 🏗️ FluxStack - Arquitetura Detalhada
+
+> **Arquitetura completa**: Como o framework funciona internamente
+
+## 📊 **Visão Geral da Arquitetura**
+
+FluxStack implementa uma arquitetura **monorepo modular** com separação clara entre framework core e código da aplicação, garantindo escalabilidade e manutenibilidade.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      FluxStack                              │
+├─────────────────────────────────────────────────────────────┤
+│  🎨 Frontend (React + Vite)                                 │
+│  ├─ Components & Pages                                      │
+│  ├─ Eden Treaty Client ←─────────────────────┐              │
+│  └─ Hooks & Utils                            │              │
+├─────────────────────────────────────────────┼──────────────┤
+│  🔌 Communication Layer                     │              │
+│  └─ Eden Treaty (Type-safe HTTP) ────────────┘              │
+├─────────────────────────────────────────────────────────────┤
+│  🚀 Backend (Elysia + Bun)                                  │
+│  ├─ Controllers (Business Logic)                            │
+│  ├─ Routes (API Endpoints)                                  │
+│  ├─ Types (Shared with Frontend)                            │
+│  └─ App Export (for Eden Treaty)                            │
+├─────────────────────────────────────────────────────────────┤
+│  ⚙️ Framework Core (Read-Only)                              │
+│  ├─ Server Framework                                        │
+│  ├─ Plugin System                                           │
+│  ├─ Build System                                            │
+│  └─ Configuration Management                                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 🎯 **Core Principles**
+
+### **1. 🔒 Separation of Concerns**
+- **`core/`**: Framework code (read-only, versioned)
+- **`app/`**: Application code (user-editable)
+- **Clear boundaries**: Framework vs Application
+
+### **2. ⚡ Type Safety First**
+- **End-to-end types**: Client ↔ Server automaticamente sincronizados
+- **Zero duplicação**: Types definidos uma vez, usados em todo lugar
+- **Compile-time validation**: Erros detectados antes do runtime
+
+### **3. 🔄 Hot Development**
+- **Independent reloading**: Backend e Frontend recarregam separadamente
+- **Fast iterations**: Mudanças refletem instantaneamente
+- **Zero downtime**: Desenvolvimento sem interrupções
+
+## 🏗️ **Arquitetura Detalhada**
+
+### **📁 Estrutura de Diretórios**
+```
+FluxStack/
+├── core/                        # 🔒 FRAMEWORK CORE
+│   ├── server/
+│   │   ├── framework.ts         # Classe principal FluxStackFramework
+│   │   └── plugins/             # Sistema de plugins built-in
+│   │       ├── logger.ts        # Logging avançado
+│   │       ├── swagger.ts       # Documentação automática
+│   │       ├── vite.ts          # Integração Vite
+│   │       └── static.ts        # Arquivos estáticos
+│   ├── config/
+│   │   ├── env-dynamic.ts       # Environment variables dinâmicas
+│   │   └── runtime-config.ts    # Configuração runtime
+│   ├── types/
+│   │   └── index.ts             # Types do framework
+│   └── build/
+│       └── index.ts             # Sistema de build
+├── app/                         # 👨‍💻 APPLICATION CODE
+│   ├── server/
+│   │   ├── controllers/         # Business logic
+│   │   ├── routes/              # API endpoints
+│   │   └── app.ts               # App type export
+│   ├── client/
+│   │   ├── src/
+│   │   │   ├── components/      # React components
+│   │   │   ├── lib/             # Eden Treaty client
+│   │   │   └── App.tsx          # Main interface
+│   │   └── public/              # Static assets
+│   └── shared/
+│       └── types/               # Shared types
+└── ai-context/                  # 📖 LLM Documentation
+```
+
+### **⚙️ Framework Core Architecture**
+
+#### **🎮 FluxStackFramework Class**
+```typescript
+export class FluxStackFramework {
+  private app: Elysia
+  private plugins: Plugin[] = []
+  
+  constructor(options: FluxStackOptions) {
+    this.app = new Elysia()
+    this.loadCorePlugins()
+    this.setupRoutes()
+  }
+  
+  // Plugin system
+  use(plugin: Plugin): this
+  
+  // Development server  
+  startDev(): Promise<void>
+  
+  // Production server
+  start(): Promise<void>
+  
+  // Build system
+  build(): Promise<void>
+}
+```
+
+#### **🔌 Plugin System**
+```typescript
+export interface Plugin {
+  name: string
+  version?: string
+  dependencies?: string[]
+  setup(context: FluxStackContext, app: Elysia): void
+}
+
+// Built-in plugins
+const corePlugins = [
+  loggerPlugin,     // Request/response logging
+  swaggerPlugin,    // API documentation
+  vitePlugin,       // Frontend integration
+  staticPlugin      // Static file serving
+]
+```
+
+### **🔄 Communication Architecture**
+
+#### **📡 Eden Treaty Integration**
+```typescript
+// Server: Export app type
+export type App = typeof appInstance
+
+// Client: Import and use
+import { treaty } from '@elysiajs/eden'
+import type { App } from '../../../server/app'
+
+const client = treaty<App>(baseUrl)
+export const api = client.api  // ✨ Full type inference
+```
+
+#### **🔒 Type Flow**
+```
+1. Server defines routes with TypeBox schemas
+2. Elysia generates TypeScript types
+3. App.ts exports combined app type  
+4. Eden Treaty imports app type
+5. Client gets automatic type inference
+6. Changes server → automatic client updates
+```
+
+## 🚀 **Runtime Architecture**
+
+### **🔄 Development Mode**
+```
+┌─────────────────┐    ┌─────────────────┐
+│   Bun Process   │    │   Vite Process  │
+│                 │    │                 │
+│ ┌─────────────┐ │    │ ┌─────────────┐ │
+│ │FluxStack    │ │    │ │React HMR    │ │
+│ │Framework    │ │    │ │Server       │ │
+│ │:3000        │ │    │ │:5173        │ │
+│ └─────────────┘ │    │ └─────────────┘ │
+└─────────────────┘    └─────────────────┘
+         │                       │
+         └─────── CORS ──────────┘
+              (Different ports)
+```
+
+### **🏭 Production Mode**
+```
+┌─────────────────────────────────┐
+│         Bun Process             │
+│                                 │
+│ ┌─────────────┐ ┌─────────────┐ │
+│ │FluxStack    │ │Static Files │ │
+│ │API Server   │ │Server       │ │
+│ │:3000/api    │ │:3000/       │ │
+│ └─────────────┘ └─────────────┘ │
+└─────────────────────────────────┘
+          Single process
+```
+
+## 🛠️ **Build Architecture**
+
+### **📦 Build Stages**
+```typescript
+// 1. Frontend Build (Vite)
+const frontendBuild = {
+  input: 'app/client/src/main.tsx',
+  output: 'dist/client/',
+  mode: 'production',
+  env: process.env
+}
+
+// 2. Backend Build (Bun)  
+const backendBuild = {
+  input: 'app/server/index.ts',
+  output: 'dist/server/',
+  target: 'bun',
+  minify: true
+}
+
+// 3. Framework Core (No build - TypeScript)
+// Core remains as TypeScript for performance
+```
+
+### **🐳 Docker Architecture**
+```dockerfile
+# Multi-stage build
+FROM oven/bun:1 as builder
+WORKDIR /app
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile
+
+# Build stage
+COPY . .
+RUN bun run build
+
+# Runtime stage  
+FROM oven/bun:1 as runtime
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+EXPOSE 3000
+CMD ["bun", "dist/index.js"]
+```
+
+## ⚡ **Performance Architecture**
+
+### **🚀 Bun Runtime Benefits**
+- **3x faster startup** vs Node.js
+- **Built-in bundler** (faster than webpack)
+- **Native fetch** & Web APIs
+- **Low memory footprint**
+
+### **📈 Elysia Performance**
+- **Zero-cost abstractions**
+- **Compile-time optimizations**  
+- **Minimal runtime overhead**
+- **Built-in validation** with TypeBox
+
+### **🔄 Hot Reload Strategy**
+```typescript
+// Backend: File watching with Bun
+Bun.watch("app/server/**/*.ts", {
+  onUpdate: () => {
+    // Restart server preserving connections
+    server.reload()
+  }
+})
+
+// Frontend: Vite HMR
+// Independent hot module replacement
+// No server restart required
+```
+
+## 🧪 **Testing Architecture**
+
+### **🔬 Test Strategy**
+```
+┌─────────────────────────────────────────┐
+│               Test Pyramid              │
+├─────────────────────────────────────────┤
+│  E2E Tests (Playwright)                 │ ← Full app tests
+├─────────────────────────────────────────┤
+│  Integration Tests (Vitest)             │ ← API + UI tests  
+├─────────────────────────────────────────┤
+│  Unit Tests (Vitest + React Testing)    │ ← Component tests
+└─────────────────────────────────────────┘
+```
+
+### **🧪 Test Configuration**
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    environment: 'jsdom',        // React testing
+    setupFiles: ['./tests/setup.ts'],
+    coverage: {
+      reporter: ['text', 'html'],
+      threshold: {
+        global: {
+          branches: 80,
+          functions: 80,
+          lines: 80,
+          statements: 80
+        }
+      }
+    }
+  }
+})
+```
+
+## 🔧 **Configuration Architecture**
+
+### **⚙️ Dynamic Environment System**
+```typescript
+// Precedence: Process Env > Runtime > .env > Defaults
+class EnvironmentManager {
+  static precedence = [
+    'process.env',     // Highest priority
+    'runtime.env',     // Runtime overrides  
+    'file.env',        // .env file
+    'defaults'         // Framework defaults
+  ]
+  
+  static get(key: string): string {
+    return this.resolveWithPrecedence(key)
+  }
+}
+```
+
+### **🎛️ Plugin Configuration**
+```typescript
+interface PluginConfig {
+  logger: {
+    level: 'debug' | 'info' | 'warn' | 'error'
+    format: 'json' | 'pretty'
+  }
+  swagger: {
+    path: string
+    title: string
+    version: string
+  }
+  vite: {
+    port: number
+    host: string
+    open: boolean
+  }
+}
+```
+
+## 🚀 **Deployment Architecture**
+
+### **☁️ Production Deployment Options**
+
+#### **1. Single Container (Recommended)**
+```yaml
+# docker-compose.yml
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=${DATABASE_URL}
+```
+
+#### **2. Microservices (Advanced)**
+```yaml
+services:
+  api:
+    build: 
+      target: api-only
+    ports:
+      - "3000:3000"
+      
+  frontend:
+    build:
+      target: frontend-only  
+    ports:
+      - "80:80"
+```
+
+#### **3. Serverless (Future)**
+```typescript
+// Planned: Vercel/Netlify adapters
+export default FluxStackFramework.createServerlessHandler({
+  platform: 'vercel' | 'netlify' | 'aws-lambda'
+})
+```
+
+## 🔮 **Future Architecture**
+
+### **📈 Planned Enhancements**
+- **Database Layer**: Native ORM integration
+- **Authentication**: Built-in auth system
+- **Real-time**: WebSocket support
+- **Microservices**: Service mesh support
+- **Observability**: Metrics & tracing
+
+### **🎯 Architecture Goals**
+- **Zero config** for common use cases
+- **Infinite customization** for advanced needs
+- **Production ready** out of the box
+- **Developer happiness** as top priority
+
+---
+
+**🎯 Esta arquitetura garante que FluxStack seja tanto simples para começar quanto poderoso para escalar!**

package/ai-context/project/overview.md

@@ -0,0 +1,213 @@
+# 🚀 FluxStack - Visão Geral do Projeto
+
+## 📋 **Resumo Executivo**
+
+**FluxStack** é um framework full-stack moderno que combina **Bun**, **Elysia.js**, **React 19** e **TypeScript** numa arquitetura monorepo unificada com **type-safety end-to-end automática** via Eden Treaty.
+
+### 🎯 **Diferenciais**
+- **⚡ Performance**: Bun runtime (3x mais rápido que Node.js)
+- **🔒 Type Safety**: Inferência automática client↔server sem declarações manuais
+- **🔥 Hot Reload**: Backend e frontend independentes
+- **📖 Auto-docs**: Swagger UI gerado automaticamente
+- **🧪 Testing**: Suite completa com Vitest
+- **🐳 Deploy**: Docker otimizado incluído
+
+## 📊 **Estado Atual (Janeiro 2025)**
+
+### ✅ **Sistema Estável**
+- **Zero erros TypeScript** (vs 200+ anteriormente)
+- **100% type inference** Eden Treaty funcionando
+- **Hot reload independente** backend/frontend
+- **Monorepo unificado** com uma instalação
+- **Response schemas** completos para documentação automática
+
+### 📈 **Estatísticas**
+- **Runtime**: Bun 1.1.34+ 
+- **Frontend**: React 19.1.0 + Vite 7.0.4
+- **Backend**: Elysia.js 1.3.7 + TypeScript 5.8.3
+- **Testing**: Vitest 3.2.4 + 100% taxa de sucesso
+- **Build**: Docker multi-stage otimizado
+
+## 🏗️ **Arquitetura Tecnológica**
+
+### **Backend Stack**
+```typescript
+// Runtime & Framework
+Bun 1.1.34+              // Runtime ultrarrápido
+Elysia.js 1.3.7          // Framework web performático
+TypeScript 5.8.3         // Type safety total
+
+// APIs & Documentação  
+Eden Treaty              // Type-safe client generation
+Swagger UI               // Documentação automática
+TypeBox                  // Validação runtime + compile-time
+```
+
+### **Frontend Stack**
+```typescript
+// UI & Build
+React 19.1.0             // UI library com Concurrent Features
+Vite 7.0.4               // Build tool + HMR ultrarrápido
+TypeScript 5.8.3         // Type safety client
+
+// Styling & State
+CSS Moderno              // Custom properties + Grid/Flexbox
+React Hooks Nativos      // useState, useEffect, etc.
+```
+
+### **DevTools & Testing**
+```typescript
+// Testing & Quality
+Vitest 3.2.4             // Test runner rápido
+JSDOM                    // DOM testing environment
+ESLint 9.30.1            // Code quality
+TypeScript Compiler      // Type checking
+
+// CI/CD & Deploy
+GitHub Actions           // Continuous integration
+Docker                   // Containerização
+Multi-stage builds       // Otimização de imagem
+```
+
+## 📁 **Estrutura do Projeto**
+
+```
+FluxStack/
+├── core/                    # 🔒 FRAMEWORK (read-only)
+│   ├── server/             # Framework Elysia + plugins
+│   ├── config/             # Sistema de configuração
+│   ├── types/              # Types do framework
+│   └── build/              # Sistema de build
+├── app/                     # 👨‍💻 CÓDIGO DA APLICAÇÃO
+│   ├── server/             # Backend (controllers, routes)
+│   │   ├── controllers/    # Lógica de negócio
+│   │   ├── routes/         # Endpoints da API
+│   │   └── app.ts          # Export do tipo para Eden Treaty
+│   ├── client/             # Frontend (React + Vite)
+│   │   ├── src/components/ # Componentes React
+│   │   ├── src/lib/        # Cliente Eden Treaty
+│   │   └── src/App.tsx     # Interface principal
+│   └── shared/             # Types compartilhados
+├── tests/                   # Testes do framework
+├── docs/                    # Documentação técnica
+└── ai-context/              # 📖 Esta documentação
+```
+
+## 🚀 **Funcionalidades Principais**
+
+### ✨ **1. Type Safety End-to-End**
+```typescript
+// ✅ Eden Treaty infere automaticamente
+const { data: user, error } = await api.users.post({
+  name: "João",
+  email: "joao@example.com"
+})
+
+// TypeScript sabe que:
+// - user: UserResponse = { success: boolean; user?: User; message?: string }
+// - error: undefined (em caso de sucesso)
+```
+
+### ⚡ **2. Hot Reload Independente**
+```bash
+bun run dev    # Backend + Frontend juntos
+# Backend recarrega sem afetar frontend
+# Frontend HMR sem reiniciar backend
+```
+
+### 📖 **3. Documentação Automática**
+```typescript
+// ✅ Swagger gerado automaticamente das rotas
+.post("/users", handler, {
+  body: t.Object({
+    name: t.String(),
+    email: t.String({ format: "email" })
+  }),
+  response: t.Object({
+    success: t.Boolean(),
+    user: t.Optional(t.Object({...}))
+  })
+})
+// → Vira documentação automática
+```
+
+### 🧪 **4. Testing Integrado**
+```bash
+bun run test        # Todos os testes
+bun run test:ui     # Interface visual
+bun run test:coverage  # Relatório cobertura
+```
+
+## 🔄 **Fluxo de Desenvolvimento**
+
+### **1. Desenvolvimento Local**
+```bash
+bun install        # Uma instalação (monorepo)
+bun run dev        # Full-stack server
+# → Backend: http://localhost:3000
+# → Frontend: http://localhost:5173  
+# → Swagger: http://localhost:3000/swagger
+```
+
+### **2. Criação de Features**
+```typescript
+// 1. Types em app/shared/
+export interface Product { id: number; name: string }
+
+// 2. Controller em app/server/controllers/
+export class ProductsController { ... }
+
+// 3. Routes em app/server/routes/  
+export const productsRoutes = new Elysia()...
+
+// 4. Frontend em app/client/src/
+const { data, error } = await api.products.get()
+```
+
+### **3. Build & Deploy**
+```bash
+bun run build     # Build otimizado
+bun run start     # Servidor produção
+# ou
+docker build .    # Container Docker
+```
+
+## 🎯 **Casos de Uso Ideais**
+
+### ✅ **Excelente Para:**
+- **APIs REST modernas** com documentação automática
+- **SPAs React** com type safety total
+- **Protótipos rápidos** com hot reload
+- **Microserviços** com alta performance
+- **Apps corporativos** com qualidade enterprise
+
+### ⚠️ **Considere Alternativas Para:**
+- **Apps server-side rendering** complexos (use Next.js)
+- **Projetos que precisam de Node.js** específico
+- **Teams sem experiência TypeScript** (curva de aprendizado)
+
+## 📈 **Roadmap & Futuro**
+
+### 🎯 **Próximas Versões**
+- **Database layer**: Integração nativa com ORMs
+- **Authentication**: Sistema de auth built-in
+- **Real-time**: WebSockets + Server-Sent Events
+- **API versioning**: Versionamento automático
+- **Monitoring**: Métricas e observabilidade
+
+### 🔮 **Visão de Longo Prazo**
+- Framework **plug-and-play** para startups
+- **Marketplace de plugins** da comunidade  
+- **Templates** para domínios específicos
+- **CLI generator** para scaffolding
+
+## 🆘 **Suporte & Comunidade**
+
+- **📖 Documentação**: Esta pasta `ai-context/`
+- **🐛 Issues**: GitHub repository
+- **💬 Discussões**: GitHub Discussions
+- **📧 Email**: Para questões privadas
+
+---
+
+**🎯 FluxStack é ideal para desenvolvedores que querem produtividade máxima com type safety garantida e performance de ponta.**