create-fluxstack 1.0.2 → 1.0.3

package/.kiro/specs/fluxstack-architecture-optimization/requirements.md

@@ -0,0 +1,127 @@
+# Requirements Document
+
+## Introduction
+
+Esta especificação define melhorias na arquitetura do FluxStack para otimizar a organização do código, performance, developer experience e manutenibilidade. O objetivo é evoluir o framework mantendo sua simplicidade e poder, mas corrigindo inconsistências estruturais e adicionando funcionalidades que faltam para um framework de produção robusto.
+
+## Requirements
+
+### Requirement 1: Reorganização da Estrutura de Pastas
+
+**User Story:** Como desenvolvedor usando FluxStack, eu quero uma estrutura de pastas mais consistente e intuitiva, para que eu possa navegar e organizar meu código de forma mais eficiente.
+
+#### Acceptance Criteria
+
+1. WHEN eu examino a estrutura do projeto THEN eu devo ver uma organização clara entre framework core, aplicação do usuário, e configurações
+2. WHEN eu procuro por arquivos relacionados THEN eles devem estar agrupados logicamente na mesma pasta ou subpasta
+3. WHEN eu adiciono novos plugins ou funcionalidades THEN deve haver um local claro e consistente para colocá-los
+4. WHEN eu trabalho com tipos compartilhados THEN deve haver uma estrutura clara que evite imports circulares
+5. WHEN eu examino a pasta core THEN ela deve estar organizada por funcionalidade (server, client, build, cli, etc.)
+
+### Requirement 2: Sistema de Build Otimizado
+
+**User Story:** Como desenvolvedor, eu quero um sistema de build mais robusto e rápido, para que eu possa ter builds confiáveis tanto em desenvolvimento quanto em produção.
+
+#### Acceptance Criteria
+
+1. WHEN eu executo `bun run build` THEN o processo deve ser otimizado e reportar progresso claramente
+2. WHEN o build falha THEN eu devo receber mensagens de erro claras e acionáveis
+3. WHEN eu faço build de produção THEN os assets devem ser otimizados (minificação, tree-shaking, etc.)
+4. WHEN eu uso build incremental THEN apenas os arquivos modificados devem ser reprocessados
+5. WHEN eu configuro diferentes targets THEN o build deve se adaptar automaticamente (Node.js, Bun, Docker)
+
+### Requirement 3: Sistema de Logging Aprimorado
+
+**User Story:** Como desenvolvedor, eu quero um sistema de logging mais estruturado e configurável, para que eu possa debugar problemas e monitorar a aplicação eficientemente.
+
+#### Acceptance Criteria
+
+1. WHEN a aplicação roda THEN os logs devem ter formato consistente com timestamps, níveis e contexto
+2. WHEN eu configuro LOG_LEVEL THEN apenas logs do nível especificado ou superior devem aparecer
+3. WHEN ocorre um erro THEN o log deve incluir stack trace, contexto da requisição e metadata relevante
+4. WHEN eu uso diferentes ambientes THEN o formato de log deve se adaptar (desenvolvimento vs produção)
+5. WHEN eu quero logs estruturados THEN deve haver suporte para JSON logging para ferramentas de monitoramento
+
+### Requirement 4: Error Handling Unificado
+
+**User Story:** Como desenvolvedor, eu quero um sistema de tratamento de erros consistente entre frontend e backend, para que eu possa lidar com erros de forma previsível e user-friendly.
+
+#### Acceptance Criteria
+
+1. WHEN ocorre um erro no backend THEN ele deve ser formatado de forma consistente com códigos de erro padronizados
+2. WHEN o frontend recebe um erro THEN ele deve ser tratado de forma consistente com mensagens user-friendly
+3. WHEN há erro de validação THEN as mensagens devem ser específicas e acionáveis
+4. WHEN ocorre erro de rede THEN deve haver retry automático e fallbacks apropriados
+5. WHEN há erro não tratado THEN deve ser logado adequadamente e não quebrar a aplicação
+
+### Requirement 5: Plugin System Aprimorado
+
+**User Story:** Como desenvolvedor, eu quero um sistema de plugins mais poderoso e flexível, para que eu possa estender o FluxStack facilmente com funcionalidades customizadas.
+
+#### Acceptance Criteria
+
+1. WHEN eu crio um plugin THEN deve haver uma API clara para hooks de lifecycle (onRequest, onResponse, onError, etc.)
+2. WHEN eu instalo um plugin THEN ele deve poder modificar configurações, adicionar rotas e middleware
+3. WHEN plugins interagem THEN deve haver um sistema de prioridades e dependências
+4. WHEN eu desenvolvo plugins THEN deve haver TypeScript support completo com tipos inferidos
+5. WHEN eu distribuo plugins THEN deve haver um sistema de descoberta e instalação simples
+
+### Requirement 6: Development Experience Melhorado
+
+**User Story:** Como desenvolvedor, eu quero uma experiência de desenvolvimento mais fluida e produtiva, para que eu possa focar na lógica de negócio ao invés de configurações.
+
+#### Acceptance Criteria
+
+1. WHEN eu inicio o desenvolvimento THEN o setup deve ser instantâneo com feedback claro do status
+2. WHEN eu faço mudanças no código THEN o hot reload deve ser rápido e confiável
+3. WHEN ocorrem erros THEN eles devem ser exibidos de forma clara no terminal e browser
+4. WHEN eu uso o CLI THEN os comandos devem ter help contextual e validação de parâmetros
+5. WHEN eu trabalho com APIs THEN deve haver ferramentas de debugging e inspeção integradas
+
+### Requirement 7: Performance Monitoring
+
+**User Story:** Como desenvolvedor, eu quero ferramentas de monitoramento de performance integradas, para que eu possa identificar e otimizar gargalos na aplicação.
+
+#### Acceptance Criteria
+
+1. WHEN a aplicação roda THEN deve coletar métricas básicas (response time, memory usage, etc.)
+2. WHEN eu acesso endpoints THEN deve haver logging de performance com timing detalhado
+3. WHEN há problemas de performance THEN deve haver alertas e sugestões de otimização
+4. WHEN eu uso em produção THEN deve haver dashboard básico de métricas
+5. WHEN integro com ferramentas externas THEN deve haver exporters para Prometheus, DataDog, etc.
+
+### Requirement 8: Gerenciamento de Estado Global
+
+**User Story:** Como desenvolvedor frontend, eu quero um padrão claro para gerenciamento de estado global, para que eu possa compartilhar estado entre componentes de forma eficiente.
+
+#### Acceptance Criteria
+
+1. WHEN eu preciso de estado global THEN deve haver uma solução integrada e type-safe
+2. WHEN o estado muda THEN os componentes devem re-renderizar automaticamente
+3. WHEN eu uso estado assíncrono THEN deve haver suporte para loading states e error handling
+4. WHEN eu persisto estado THEN deve haver integração com localStorage/sessionStorage
+5. WHEN eu debugo estado THEN deve haver ferramentas de inspeção integradas
+
+### Requirement 9: Configuração Avançada
+
+**User Story:** Como desenvolvedor, eu quero um sistema de configuração mais flexível e poderoso, para que eu possa customizar o comportamento do framework para diferentes cenários.
+
+#### Acceptance Criteria
+
+1. WHEN eu configuro o framework THEN deve haver validação de configuração com mensagens claras
+2. WHEN eu uso diferentes ambientes THEN as configurações devem ser carregadas automaticamente
+3. WHEN eu override configurações THEN deve haver precedência clara (env vars > config file > defaults)
+4. WHEN eu adiciono configurações customizadas THEN elas devem ser type-safe e documentadas
+5. WHEN eu valido configurações THEN deve haver schema validation com error reporting detalhado
+
+### Requirement 10: Tooling e Utilitários
+
+**User Story:** Como desenvolvedor, eu quero ferramentas e utilitários integrados que facilitem tarefas comuns de desenvolvimento, para que eu possa ser mais produtivo.
+
+#### Acceptance Criteria
+
+1. WHEN eu preciso gerar código THEN deve haver generators para controllers, routes, components, etc.
+2. WHEN eu faço deploy THEN deve haver comandos integrados para diferentes plataformas
+3. WHEN eu analiso o projeto THEN deve haver ferramentas de análise de bundle size e dependencies
+4. WHEN eu migro versões THEN deve haver scripts de migração automática
+5. WHEN eu trabalho em equipe THEN deve haver ferramentas de linting e formatting configuradas

package/.kiro/specs/fluxstack-architecture-optimization/tasks.md

@@ -0,0 +1,330 @@
+# Implementation Plan
+
+- [x] 1. Setup and Configuration System Refactoring
+
+
+
+
+  - Create new configuration system with schema validation and environment handling
+  - Move fluxstack.config.ts to root and implement new configuration structure
+  - Implement configuration loader with validation and environment-specific overrides
+  - _Requirements: 1.1, 9.1, 9.2, 9.3, 9.4, 9.5_
+
+- [x] 1.1 Create Enhanced Configuration Schema
+
+
+  - Write TypeScript interfaces for comprehensive FluxStackConfig
+  - Implement JSON schema validation for configuration
+  - Create configuration loader with environment variable support
+  - _Requirements: 9.1, 9.2, 9.3_
+
+- [x] 1.2 Implement Configuration Validation System
+
+
+  - Create configuration validator with detailed error reporting
+  - Implement environment-specific configuration merging
+  - Add configuration precedence handling (env vars > config file > defaults)
+  - _Requirements: 9.1, 9.4, 9.5_
+
+- [x] 1.3 Move and Update Main Configuration File
+
+
+  - Move fluxstack.config.ts from config/ to root directory
+  - Update all imports and references to new configuration location
+  - Implement backward compatibility for existing configuration structure
+  - _Requirements: 1.1, 1.2, 9.1_
+
+- [x] 2. Core Framework Restructuring
+
+
+
+
+  - Reorganize core/ directory structure according to new design
+  - Create new framework class with enhanced plugin system
+  - Implement modular core utilities (logger, errors, monitoring)
+  - _Requirements: 1.1, 1.2, 1.3, 5.1, 5.2_
+
+- [x] 2.1 Reorganize Core Directory Structure
+
+
+  - Create new directory structure: framework/, plugins/, build/, cli/, config/, utils/, types/
+  - Move existing files to appropriate new locations
+  - Update all import paths throughout the codebase
+  - _Requirements: 1.1, 1.2, 1.3_
+
+- [x] 2.2 Create Enhanced Framework Class
+
+
+  - Refactor FluxStackFramework class with new plugin system integration
+  - Implement lifecycle hooks for plugins (onServerStart, onServerStop, etc.)
+  - Add configuration injection and validation to framework initialization
+  - _Requirements: 5.1, 5.2, 5.3_
+
+- [x] 2.3 Implement Core Types System
+
+
+  - Create comprehensive TypeScript types for all core interfaces
+  - Implement plugin types with lifecycle hooks and configuration schemas
+  - Add build system types and configuration interfaces
+  - _Requirements: 1.4, 5.4, 2.1_
+
+- [x] 3. Enhanced Plugin System Implementation
+
+
+
+  - Create plugin registry with dependency management and load ordering
+  - Implement enhanced plugin interface with lifecycle hooks
+  - Refactor existing plugins to use new plugin system
+  - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5_
+
+- [x] 3.1 Create Plugin Registry System
+
+
+  - Implement PluginRegistry class with registration, dependency validation, and load ordering
+  - Create plugin discovery mechanism for built-in and external plugins
+  - Add plugin configuration management and validation
+  - _Requirements: 5.1, 5.3, 5.5_
+
+- [x] 3.2 Implement Enhanced Plugin Interface
+
+
+  - Create comprehensive Plugin interface with all lifecycle hooks
+  - Implement PluginContext with access to config, logger, app, and utilities
+  - Add plugin priority system and dependency resolution
+  - _Requirements: 5.1, 5.2, 5.4_
+
+- [x] 3.3 Refactor Built-in Plugins
+
+
+  - Update logger plugin to use new plugin interface and enhanced logging system
+  - Refactor swagger plugin with new configuration and lifecycle hooks
+  - Update vite plugin with improved integration and error handling
+  - _Requirements: 5.1, 5.2, 3.1_
+
+
+
+- [x] 3.4 Create Monitoring Plugin
+
+
+
+
+  - Implement performance monitoring plugin with metrics collection
+  - Add HTTP request/response timing and system metrics
+  - Create metrics exporters for Prometheus and other monitoring systems
+  - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5_
+
+- [ ] 4. Enhanced Logging System
+  - Create structured logging system with multiple transports and formatters
+  - Implement contextual logging with request correlation
+  - Add performance logging with timing utilities
+  - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
+
+- [ ] 4.1 Create Core Logging Infrastructure
+  - Implement FluxStackLogger class with multiple transport support
+  - Create log formatters for development (pretty) and production (JSON)
+  - Add log level filtering and contextual logging capabilities
+  - _Requirements: 3.1, 3.2, 3.4_
+
+- [ ] 4.2 Implement Log Transports
+  - Create console transport with colored output for development
+  - Implement file transport with rotation and compression
+  - Add structured JSON transport for production logging
+  - _Requirements: 3.1, 3.4, 3.5_
+
+- [ ] 4.3 Add Performance and Request Logging
+  - Implement request correlation IDs and contextual logging
+  - Create timing utilities for performance measurement
+  - Add automatic request/response logging with duration tracking
+  - _Requirements: 3.2, 3.3, 7.2_
+
+- [ ] 5. Unified Error Handling System
+  - Create comprehensive error classes with codes and context
+  - Implement error handler middleware with consistent formatting
+  - Add error recovery strategies and user-friendly messaging
+  - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_
+
+- [ ] 5.1 Create Error Class Hierarchy
+  - Implement FluxStackError base class with code, statusCode, and context
+  - Create specific error classes (ValidationError, NotFoundError, etc.)
+  - Add error serialization for consistent API responses
+  - _Requirements: 4.1, 4.2, 4.3_
+
+- [ ] 5.2 Implement Error Handler Middleware
+  - Create centralized error handler with logging and metrics integration
+  - Implement error context preservation and stack trace handling
+  - Add user-friendly error message generation
+  - _Requirements: 4.1, 4.2, 4.5_
+
+- [ ] 5.3 Add Client-Side Error Handling
+  - Update Eden Treaty client with consistent error handling
+  - Implement error recovery strategies (retry, fallback)
+  - Create user-friendly error message utilities
+  - _Requirements: 4.2, 4.4, 4.5_
+
+- [ ] 6. Build System Optimization
+  - Create modular build system with bundler, optimizer, and target support
+  - Implement incremental builds and caching
+  - Add build performance monitoring and optimization
+  - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5_
+
+- [ ] 6.1 Create Enhanced Builder Class
+  - Implement FluxStackBuilder with modular architecture (bundler, optimizer)
+  - Add build validation, cleaning, and manifest generation
+  - Create build result reporting with timing and metrics
+  - _Requirements: 2.1, 2.2, 2.3_
+
+- [ ] 6.2 Implement Build Optimization
+  - Create Optimizer class with minification, tree-shaking, and compression
+  - Add bundle analysis and size optimization
+  - Implement code splitting and chunk optimization
+  - _Requirements: 2.3, 2.4, 2.5_
+
+- [ ] 6.3 Add Build Targets Support
+  - Implement different build targets (bun, node, docker)
+  - Create target-specific optimizations and configurations
+  - Add build manifest generation for deployment
+  - _Requirements: 2.1, 2.5_
+
+- [ ] 7. CLI Enhancement and Code Generation
+  - Enhance CLI with better help, validation, and error handling
+  - Add code generation commands for common patterns
+  - Implement deployment helpers and project analysis tools
+  - _Requirements: 6.1, 6.2, 6.3, 6.4, 10.1, 10.2, 10.3_
+
+- [ ] 7.1 Enhance Core CLI Infrastructure
+  - Improve CLI command structure with better help and validation
+  - Add command parameter validation and error handling
+  - Implement progress reporting and user feedback
+  - _Requirements: 6.1, 6.4, 6.5_
+
+- [ ] 7.2 Create Code Generation System
+  - Implement generators for controllers, routes, components, and services
+  - Create template system for code generation
+  - Add interactive prompts for generator configuration
+  - _Requirements: 10.1, 10.4_
+
+- [ ] 7.3 Add Development Tools
+  - Create project analysis tools (bundle size, dependencies)
+  - Implement deployment helpers for different platforms
+  - Add migration scripts for version updates
+  - _Requirements: 10.2, 10.3, 10.4_
+
+- [ ] 8. State Management Integration
+  - Create integrated state management solution for frontend
+  - Implement React hooks and utilities for state access
+  - Add persistence and middleware support
+  - _Requirements: 8.1, 8.2, 8.3, 8.4, 8.5_
+
+- [ ] 8.1 Create Core State Management System
+  - Implement FluxStackStore class with type-safe state management
+  - Create state slices pattern for modular state organization
+  - Add middleware support for logging, persistence, and async actions
+  - _Requirements: 8.1, 8.2, 8.4_
+
+- [ ] 8.2 Implement React Integration
+  - Create React hooks (useAppStore, useAppSelector) for state access
+  - Implement context provider for store access
+  - Add React DevTools integration for debugging
+  - _Requirements: 8.1, 8.2, 8.5_
+
+- [ ] 8.3 Add State Persistence
+  - Implement localStorage and sessionStorage persistence
+  - Create selective persistence with whitelist/blacklist
+  - Add state hydration and serialization utilities
+  - _Requirements: 8.4_
+
+- [ ] 9. Performance Monitoring Implementation
+  - Create metrics collection system with HTTP and system metrics
+  - Implement performance profiling and monitoring
+  - Add metrics exporters for external monitoring systems
+  - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5_
+
+- [ ] 9.1 Create Metrics Collection System
+  - Implement MetricsCollector class with HTTP, system, and custom metrics
+  - Add automatic metrics collection for requests, responses, and system resources
+  - Create metrics registry for custom application metrics
+  - _Requirements: 7.1, 7.2, 7.3_
+
+- [ ] 9.2 Implement Performance Profiling
+  - Create performance profiler for identifying bottlenecks
+  - Add request tracing and timing analysis
+  - Implement memory usage monitoring and leak detection
+  - _Requirements: 7.2, 7.3_
+
+- [ ] 9.3 Add Metrics Export System
+  - Create metrics exporters for Prometheus, DataDog, and other systems
+  - Implement basic metrics dashboard for development
+  - Add alerting capabilities for performance issues
+  - _Requirements: 7.4, 7.5_
+
+- [ ] 10. Application Structure Improvements
+  - Reorganize app/ directory with better separation of concerns
+  - Create service layer and improved controller structure
+  - Add middleware organization and custom middleware support
+  - _Requirements: 1.1, 1.2, 1.3, 1.4_
+
+- [ ] 10.1 Reorganize App Directory Structure
+  - Create new app structure with controllers/, services/, middleware/, models/
+  - Move existing code to appropriate new locations
+  - Update imports and references throughout the application
+  - _Requirements: 1.1, 1.2, 1.3_
+
+- [ ] 10.2 Implement Service Layer Pattern
+  - Create service classes for business logic separation
+  - Refactor controllers to use services for business operations
+  - Add dependency injection pattern for service management
+  - _Requirements: 1.2, 1.3_
+
+- [ ] 10.3 Enhance Frontend Structure
+  - Create organized component structure with pages/, hooks/, store/
+  - Implement proper state management integration
+  - Add improved API client with error handling
+  - _Requirements: 1.1, 1.2, 8.1, 8.2_
+
+- [ ] 11. Testing Infrastructure Updates
+  - Update test utilities for new architecture
+  - Create comprehensive test fixtures and mocks
+  - Add performance and integration testing capabilities
+  - _Requirements: All requirements need updated tests_
+
+- [ ] 11.1 Update Test Infrastructure
+  - Create FluxStackTestUtils with new architecture support
+  - Update test fixtures for new configuration and plugin systems
+  - Implement test database and state management utilities
+  - _Requirements: All requirements_
+
+- [ ] 11.2 Create Comprehensive Test Suite
+  - Write unit tests for all new core components
+  - Create integration tests for plugin system and configuration
+  - Add performance tests for build system and runtime
+  - _Requirements: All requirements_
+
+- [ ] 11.3 Add E2E Testing Capabilities
+  - Implement end-to-end testing for complete user workflows
+  - Create test scenarios for development and production modes
+  - Add automated testing for CLI commands and code generation
+  - _Requirements: 6.1, 6.2, 10.1, 10.2_
+
+- [ ] 12. Documentation and Migration
+  - Create comprehensive documentation for new architecture
+  - Write migration guides for existing projects
+  - Add examples and best practices documentation
+  - _Requirements: All requirements need documentation_
+
+- [ ] 12.1 Create Architecture Documentation
+  - Document new directory structure and organization principles
+  - Create plugin development guide with examples
+  - Write configuration reference and best practices
+  - _Requirements: 1.1, 1.2, 5.1, 5.2, 9.1_
+
+- [ ] 12.2 Write Migration Guide
+  - Create step-by-step migration guide for existing projects
+  - Implement automated migration scripts where possible
+  - Document breaking changes and compatibility considerations
+  - _Requirements: All requirements_
+
+- [ ] 12.3 Add Examples and Best Practices
+  - Create example projects showcasing new features
+  - Write best practices guide for different use cases
+  - Add troubleshooting guide for common issues
+  - _Requirements: All requirements_

package/CLAUDE.md

@@ -0,0 +1,200 @@
+# 🤖 FluxStack - AI Context Documentation
+
+> **IMPORTANTE**: Esta documentação foi **reorganizada e modernizada** para melhor suporte a LLMs.
+
+## 📖 **Nova Documentação AI**
+
+👉 **Acesse a documentação completa em**: [`ai-context/`](./ai-context/)
+
+### ⚡ **Início Rápido para LLMs**
+- **[`ai-context/00-QUICK-START.md`](./ai-context/00-QUICK-START.md)** - Entenda tudo em 2 minutos
+- **[`ai-context/README.md`](./ai-context/README.md)** - Navegação completa
+
+### 🎯 **Documentos Principais**
+- **[Development Patterns](./ai-context/development/patterns.md)** - Padrões e boas práticas
+- **[Eden Treaty Guide](./ai-context/development/eden-treaty-guide.md)** - Guia completo Eden Treaty
+- **[CRUD Example](./ai-context/examples/crud-complete.md)** - Exemplo prático completo
+- **[Troubleshooting](./ai-context/reference/troubleshooting.md)** - Solução de problemas
+
+### 🔥 **Mudanças Recentes**
+- **[Eden Treaty Refactor](./ai-context/recent-changes/eden-treaty-refactor.md)** - Refatoração crítica
+- **[Type Inference Fix](./ai-context/recent-changes/type-inference-fix.md)** - Correção de tipos
+
+---
+
+## 🚀 **FluxStack - Overview Atualizado**
+
+**FluxStack** é um framework full-stack TypeScript moderno que combina:
+
+### 🛠️ **Stack Tecnológica (Janeiro 2025)**
+- **Runtime**: Bun 1.2.20 (3x mais rápido que Node.js)
+- **Backend**: Elysia.js 1.4.6 (ultra-performático)
+- **Frontend**: React 19.1.0 + Vite 7.0.4
+- **Language**: TypeScript 5.9.2 (100% type-safe)
+- **Communication**: Eden Treaty com inferência automática
+- **Docs**: Swagger UI gerado automaticamente
+- **Testing**: Vitest + React Testing Library
+- **Deploy**: Docker otimizado
+
+### ✨ **Estado Atual (Validado)**
+- **✅ Eden Treaty Nativo**: Type inference automática funcionando perfeitamente
+- **✅ Zero Tipos Unknown**: Inferência corrigida após refatoração
+- **✅ Monorepo Unificado**: Uma instalação, hot reload independente
+- **✅ APIs Funcionando**: Health check e CRUD operacionais
+- **✅ Frontend Ativo**: React 19 + Vite rodando na porta 5173
+- **✅ Backend Ativo**: Elysia + Bun rodando na porta 3000
+
+## 📁 **Arquitetura Atual Validada**
+
+```
+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 reorganizada
+```
+
+## 🔄 **Estado Atual da Interface**
+
+### **Frontend Redesignado (App.tsx)**
+- **Interface em abas integradas**: Demo interativo, API Docs, Tests
+- **Demo CRUD**: Usuários usando Eden Treaty nativo
+- **Swagger UI**: Documentação automática integrada
+- **Type Safety**: Eden Treaty com inferência automática
+
+### **Backend Robusto (Elysia + Bun)**
+- **API RESTful**: Endpoints CRUD completos
+- **Response Schemas**: Documentação automática via TypeBox
+- **Error Handling**: Tratamento consistente de erros
+- **Hot Reload**: Recarregamento automático
+
+## 🎯 **Funcionalidades Implementadas (Validadas)**
+
+### ✅ **1. Type Safety End-to-End**
+```typescript
+// ✅ Eden Treaty infere automaticamente após refatoração
+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 (3000) + Frontend (5173)
+bun run dev:clean    # ✅ Output limpo (sem logs HEAD do Elysia)
+```
+
+### ✅ **3. APIs Funcionais**
+- **Health Check**: `GET /api/health` ✅
+- **Users CRUD**: `GET|POST|PUT|DELETE /api/users` ✅
+- **Swagger Docs**: `GET /swagger` ✅
+
+### ✅ **4. Environment Variables Dinâmicas**
+- **Sistema robusto**: Precedência clara
+- **Testing endpoint**: `/api/env-test`
+- **Validação automática**: Environment vars
+
+## 🚨 **Regras Críticas (Atualizadas)**
+
+### ❌ **NUNCA FAZER**
+- Editar arquivos em `core/` (framework read-only)
+- ~~Usar `apiCall()` wrapper~~ ✅ **REMOVIDO** - quebrava type inference
+- Criar types manuais para Eden Treaty
+- Ignorar response schemas nas rotas
+
+### ✅ **SEMPRE FAZER**
+- Trabalhar em `app/` (código da aplicação)
+- **Usar Eden Treaty nativo**: `const { data, error } = await api.users.get()`
+- Manter types compartilhados em `app/shared/`
+- Definir response schemas para documentação automática
+- Testar com `bun run dev`
+
+## 🔧 **Comandos Validados**
+
+```bash
+# Desenvolvimento
+bun run dev              # ✅ Full-stack (recomendado)
+bun run dev:clean        # ✅ Output limpo
+bun run dev:backend      # ✅ Backend apenas (porta 3001)
+bun run dev:frontend     # ✅ Frontend apenas (porta 5173)
+
+# Build e produção  
+bun run build           # ✅ Build completo
+bun run start           # ✅ Servidor de produção
+
+# Testes e validação
+bun run test            # ✅ Suite de testes
+bunx tsc --noEmit       # ✅ Verificação TypeScript
+curl http://localhost:3000/api/health  # ✅ Health check
+```
+
+## 📊 **URLs de Acesso (Validadas)**
+
+- **🚀 Backend API**: http://localhost:3000
+- **⚛️ Frontend React**: http://localhost:5173  
+- **📋 Swagger Docs**: http://localhost:3000/swagger
+- **🩺 Health Check**: http://localhost:3000/api/health
+- **👥 Users API**: http://localhost:3000/api/users
+
+## 🔥 **Mudanças Importantes v1.4→v1.5**
+
+### **✅ Eden Treaty Refatoração (Setembro 2025)**
+- **Problema resolvido**: Wrapper `apiCall()` quebrava type inference
+- **Solução implementada**: Eden Treaty nativo preserva tipos automáticos
+- **Resultado**: Zero tipos `unknown`, autocomplete perfeito
+
+### **✅ Response Schemas Implementados**
+- **Todas as rotas**: Schemas TypeBox para inferência
+- **Documentação automática**: Swagger UI atualizado
+- **Type inference**: Eden Treaty funcionando 100%
+
+### **✅ Monorepo Estabilizado**
+- **Uma instalação**: `bun install` para todo o projeto
+- **Hot reload independente**: Backend e frontend separados
+- **Build otimizado**: Sistema unificado
+
+## 🎯 **Próximos Passos Sugeridos**
+
+### **Funcionalidades Pendentes**
+1. **Database integration** - ORM nativo
+2. **Authentication system** - Auth built-in
+3. **Real-time features** - WebSockets/SSE
+4. **API versioning** - Versionamento automático
+
+### **Melhorias Técnicas**
+- Middleware de validação avançado
+- Cache de responses
+- Bundle size optimization
+- Monitoring e métricas
+
+## 🆘 **Suporte e Troubleshooting**
+
+1. **Erro específico?** → [`ai-context/reference/troubleshooting.md`](./ai-context/reference/troubleshooting.md)
+2. **Como fazer X?** → [`ai-context/development/patterns.md`](./ai-context/development/patterns.md)
+3. **Eden Treaty?** → [`ai-context/development/eden-treaty-guide.md`](./ai-context/development/eden-treaty-guide.md)
+4. **Não entendo nada?** → [`ai-context/00-QUICK-START.md`](./ai-context/00-QUICK-START.md)
+
+---
+
+**🎯 Objetivo**: Capacitar LLMs a trabalhar eficientemente com FluxStack, seguindo padrões estabelecidos e garantindo código de alta qualidade com type safety automática.
+
+**📅 Última atualização**: Janeiro 2025 - Documentação completamente reorganizada e validada.