📂 Estrutura de Pastas Profissional

Conceito Principal

Cognitive Load: Carga cognitiva e o esforco mental necessario para entender algo. Quando voce abre um projeto e ve 50 arquivos na raiz sem organizacao, seu cerebro gasta energia tentando classificar mentalmente o que cada arquivo faz. Isso e carga cognitiva desperdicada. Uma estrutura clara reduz essa carga porque a organizacao ja comunica a funcao de cada parte. Voce ve "agents/" e ja sabe onde estao os agentes. Ve "tools/" e sabe onde estao as ferramentas. Zero esforco mental.

Onboarding Time: O tempo que um novo desenvolvedor leva para fazer o primeiro commit produtivo. Em projetos bem estruturados, esse tempo e de horas. Em projetos mal organizados, pode ser dias ou semanas. A estrutura de pastas e o mapa do projeto. Se o mapa e claro, qualquer pessoa encontra o caminho. Se o mapa e confuso, ate gente experiente se perde.

AI Context: Quando voce usa Claude, Copilot ou qualquer LLM para gerar codigo, a IA usa a estrutura do projeto como contexto para suas decisoes. Se ela ve uma pasta agents/ com arquivos bem nomeados (claude.ts, ollama.ts), ela entende o padrao e gera um novo agente seguindo a mesma convencao. Se ela ve um amontoado de arquivos sem padrao, ela gera codigo que reflete essa bagunca. Boa estrutura funciona como um system prompt implicito para qualquer IA que toque o projeto.

O ponto central: a estrutura de pastas nao e sobre onde os arquivos ficam. E sobre como o conhecimento do projeto e comunicado. Para humanos, e legibilidade. Para IAs, e contexto. Para o time, e produtividade.

Conceito Principal

Monorepo e manter todo o codigo num unico repositorio. O bot, o dashboard, os agentes, as ferramentas, os scripts de deploy. Tudo junto. A grande vantagem para plataformas de agentes e o contexto compartilhado. Quando voce pede para a IA "criar um novo agente", ela ve a pasta agents/ com todos os agentes existentes, ve as interfaces, ve como sao chamados pelo router, e gera codigo consistente. Num monorepo, a IA tem visao completa do sistema.

Quando Monorepo Ganha: Projetos com equipe de ate 10-15 pessoas. Componentes fortemente acoplados que mudam juntos (bot + dashboard + agentes). Quando voce quer que a IA tenha contexto total para gerar codigo. Quando mudancas em uma parte exigem mudancas em outra (mudar a interface de um agente requer atualizar o router). Monorepo permite fazer tudo num unico commit atomico.

Multi-repo e separar cada componente em seu proprio repositorio: um repo para o bot, outro para o dashboard, outro para cada agente independente. A vantagem e isolamento total. Cada repo tem seu CI/CD, suas dependencias, seu ciclo de deploy. Um bug no dashboard nao afeta o deploy do bot.

Quando Multi-repo Ganha: Times grandes (20+ pessoas) onde equipes diferentes cuidam de componentes diferentes. Componentes com ciclos de vida independentes (o dashboard muda toda semana, o bot muda todo mes). Quando voce precisa de isolamento forte de dependencias (o bot usa Node 18, o ML pipeline usa Python 3.11). Microsservicos com APIs bem definidas entre si.

Ferramentas de Monorepo: Turborepo (da Vercel, focado em velocidade de build), Nx (da Nrwl, focado em dependencias inteligentes), Lerna (classico, mais simples). Essas ferramentas resolvem o principal problema do monorepo: builds lentos. Elas detectam quais pacotes mudaram e buildam apenas o necessario. Um push que muda so o dashboard nao rebuilda o bot.

Conceito Principal

O principio central da Clean Architecture e a Regra da Dependencia: dependencias de codigo so apontam para dentro, nunca para fora. A camada de dominio (regras de negocio) nao sabe que PostgreSQL existe. Nao sabe que Telegram existe. Nao sabe que OpenAI existe. Ela define interfaces (contratos), e as camadas externas implementam esses contratos.

Domain Layer (centro): Entidades e regras de negocio puras. Para uma plataforma de agentes: a interface Agent (recebe mensagem, retorna resposta), a interface Tool (recebe parametros, executa acao), as regras de roteamento (como decidir qual agente responde). Esse codigo nao importa nenhuma biblioteca externa. E TypeScript puro.

Application Layer: Casos de uso que orquestram o dominio. "Processar mensagem do usuario" e um caso de uso: recebe a mensagem, chama o router (dominio), seleciona o agente (dominio), executa (dominio), salva o historico (interface de persistencia). O caso de uso sabe a ordem das operacoes, mas nao sabe os detalhes de implementacao.

Infrastructure Layer (borda): Implementacoes concretas das interfaces do dominio. O adapter para Telegram que implementa a interface de "canal de entrada". O adapter para PostgreSQL que implementa a interface de "persistencia". O adapter para OpenAI que implementa a interface de "provedor de IA". Se amanha voce trocar PostgreSQL por MongoDB, so muda o adapter. O dominio e os casos de uso nao mudam uma linha.

Dependency Inversion: Em vez de o agente importar diretamente o modulo do OpenAI, o agente depende de uma interface AIProvider. Na inicializacao, voce injeta a implementacao concreta (OpenAIProvider, AnthropicProvider, OllamaProvider). Isso e inversao de dependencia na pratica: o codigo de alto nivel define o contrato, o codigo de baixo nivel implementa.

// domain/interfaces/ai-provider.ts
export interface AIProvider {
  name: string;
  generate(prompt: string, context: string): Promise<AIResponse>;
}

// domain/interfaces/message-store.ts
export interface MessageStore {
  save(chatId: string, message: Message): Promise<void>;
  getHistory(chatId: string, limit: number): Promise<Message[]>;
}

// infrastructure/providers/openai-provider.ts
import OpenAI from 'openai';
import { AIProvider, AIResponse } from '../../domain/interfaces/ai-provider';

export class OpenAIProvider implements AIProvider {
  name = 'openai';
  private client: OpenAI;

  constructor(apiKey: string) {
    this.client = new OpenAI({ apiKey });
  }

  async generate(prompt: string, context: string): Promise<AIResponse> {
    const response = await this.client.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'system', content: context }, { role: 'user', content: prompt }],
    });
    return { text: response.choices[0].message.content, tokens: response.usage };
  }
}

Conceito Principal

Layer Folders (Organizacao por Tipo): O classico. Uma pasta para controllers, uma para services, uma para models, uma para routes. Cada pasta agrupa arquivos pelo que eles sao, nao pelo que eles fazem.

# Layer Folders (por tipo)
src/
├── controllers/
│   ├── auth.controller.ts
│   ├── chat.controller.ts
│   └── billing.controller.ts
├── services/
│   ├── auth.service.ts
│   ├── chat.service.ts
│   └── billing.service.ts
├── models/
│   ├── user.model.ts
│   ├── conversation.model.ts
│   └── subscription.model.ts
└── routes/
    ├── auth.routes.ts
    ├── chat.routes.ts
    └── billing.routes.ts

O problema: para entender tudo sobre "chat", voce precisa abrir 4 pastas diferentes. Para adicionar uma feature nova, precisa criar um arquivo em cada pasta. E cada pasta cresce horizontalmente sem limite (50 controllers numa pasta so).

Feature Folders (Organizacao por Funcionalidade): Agrupa tudo que pertence a uma feature no mesmo lugar. Controller, service, model, routes de "chat" ficam juntos em chat/.

# Feature Folders (por funcionalidade)
src/
├── auth/
│   ├── auth.controller.ts
│   ├── auth.service.ts
│   ├── auth.model.ts
│   ├── auth.routes.ts
│   └── auth.test.ts
├── chat/
│   ├── chat.controller.ts
│   ├── chat.service.ts
│   ├── chat.model.ts
│   ├── chat.routes.ts
│   └── chat.test.ts
└── billing/
    ├── billing.controller.ts
    ├── billing.service.ts
    ├── billing.model.ts
    ├── billing.routes.ts
    └── billing.test.ts

A vantagem: para entender tudo sobre "chat", voce abre uma unica pasta. Para adicionar uma feature nova, cria uma unica pasta. Para deletar uma feature, deleta uma unica pasta. Alta coesao, baixo acoplamento.

Abordagem Hibrida (recomendada): Use feature folders para o codigo de negocio e layer folders para infraestrutura compartilhada. Agents/, tools/, skills/ sao feature folders. Config/, middleware/, lib/ sao layer folders que servem a todas as features.

# Hibrido (recomendado para plataformas de agentes)
src/
├── agents/          # Feature: cada agente autocontido
│   ├── claude/
│   ├── ollama/
│   └── openrouter/
├── tools/           # Feature: cada tool autocontida
│   ├── web-search/
│   └── file-read/
├── channels/        # Feature: cada canal autocontido
│   ├── telegram/
│   └── api/
├── lib/             # Compartilhado: utilidades genericas
│   ├── logger.ts
│   └── errors.ts
├── config/          # Compartilhado: configuracao
│   └── env.ts
└── middleware/      # Compartilhado: middlewares
    ├── auth.ts
    └── rate-limit.ts

Conceito Principal

Barrel Exports (index.ts): Um barrel e um arquivo index.ts que re-exporta os itens publicos de uma pasta. Ele funciona como a API publica de um modulo. O resto do sistema importa do barrel, nunca de arquivos internos. Isso cria uma fronteira clara: o que esta no index.ts e publico, o que nao esta e detalhe de implementacao.

// agents/index.ts (barrel export)
export { ClaudeAgent } from './claude';
export { OllamaAgent } from './ollama';
export { OpenRouterAgent } from './openrouter';
export { createAgent } from './factory';
export type { Agent, AgentConfig } from './types';

// Em qualquer outro lugar do sistema:
import { ClaudeAgent, createAgent } from '../agents';
// NUNCA: import { ClaudeAgent } from '../agents/claude/internal-stuff';

Naming Conventions: Nomes previsíveis eliminam decisoes desnecessarias. Adote um padrao e siga religiosamente:

# Convencao recomendada para plataformas de agentes
Arquivos:    kebab-case     → web-search.ts, claude-agent.ts
Classes:     PascalCase     → WebSearchTool, ClaudeAgent
Funcoes:     camelCase      → createAgent(), processMessage()
Constantes:  UPPER_SNAKE    → MAX_TOKENS, DEFAULT_MODEL
Tipos:       PascalCase     → AgentConfig, ToolResult
Pastas:      kebab-case     → web-search/, rate-limiter/
Env vars:    UPPER_SNAKE    → OPENAI_API_KEY, TELEGRAM_TOKEN

Path Aliases: Em vez de imports com caminhos relativos longos (import { logger } from '../../../../lib/logger'), configure path aliases no tsconfig.json. Isso torna os imports limpos, legíveis e independentes da posicao do arquivo no projeto.

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@agents/*": ["src/agents/*"],
      "@tools/*": ["src/tools/*"],
      "@lib/*": ["src/lib/*"],
      "@config/*": ["src/config/*"]
    }
  }
}

// Agora em qualquer arquivo:
import { ClaudeAgent } from '@agents';
import { logger } from '@lib/logger';
import { env } from '@config/env';

Para Node.js resolver os aliases em runtime, use tsx (que ja resolve automaticamente) ou configure o modulo tsconfig-paths. Para bundlers como esbuild ou webpack, configure os aliases no arquivo de configuracao do bundler tambem.

Conceito Principal

O exercicio cobre 5 entregas concretas. Ao final, voce tera um projeto esqueleto pronto para desenvolvimento, com convencoes definidas e configuracoes profissionais.

Entrega 1 - Estrutura de Pastas: Crie a arvore completa usando mkdir. Cada diretorio tem uma razao de existir.

# Criar toda a estrutura de uma vez
mkdir -p src/agents/claude src/agents/ollama src/agents/openrouter
mkdir -p src/tools/web-search src/tools/file-read src/tools/db-query
mkdir -p src/channels/telegram src/channels/api
mkdir -p src/skills/gmail src/skills/calendar
mkdir -p src/memory
mkdir -p src/lib
mkdir -p src/config
mkdir -p src/middleware
mkdir -p prompts/agents
mkdir -p docs/architecture

Entrega 2 - Index Files (Barrel Exports): Crie um index.ts em cada pasta de feature. Mesmo que vazio por enquanto, o arquivo ja estabelece o padrao de que tudo e acessado pelo barrel.

# Criar todos os index files
touch src/agents/index.ts
touch src/agents/claude/index.ts
touch src/agents/ollama/index.ts
touch src/agents/openrouter/index.ts
touch src/tools/index.ts
touch src/tools/web-search/index.ts
touch src/tools/file-read/index.ts
touch src/tools/db-query/index.ts
touch src/channels/index.ts
touch src/channels/telegram/index.ts
touch src/channels/api/index.ts
touch src/skills/index.ts
touch src/memory/index.ts
touch src/lib/index.ts
touch src/config/index.ts
touch src/config/env.ts
touch src/middleware/index.ts

Entrega 3 - Path Aliases: Configure o tsconfig.json com aliases para todos os modulos principais.

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "baseUrl": ".",
    "paths": {
      "@agents/*": ["src/agents/*"],
      "@agents": ["src/agents/index.ts"],
      "@tools/*": ["src/tools/*"],
      "@tools": ["src/tools/index.ts"],
      "@channels/*": ["src/channels/*"],
      "@skills/*": ["src/skills/*"],
      "@memory/*": ["src/memory/*"],
      "@lib/*": ["src/lib/*"],
      "@config/*": ["src/config/*"],
      "@middleware/*": ["src/middleware/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Entrega 4 - Arquivos de Configuracao: .env.example, .gitignore, .eslintrc com naming conventions, e package.json com scripts basicos.

# .env.example
TELEGRAM_TOKEN=bot-token-here
ALLOWED_CHAT_ID=your-chat-id
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
OLLAMA_HOST=http://localhost:11434
PORT=3000
NODE_ENV=development

# .gitignore
.env
node_modules/
dist/
*.pem
credentials.json

Entrega 5 - Validacao: Rode a arvore de diretorios e confirme que a estrutura esta completa. Faca o primeiro commit com a mensagem "feat: project scaffold with folder structure, barrel exports, and path aliases".

# Validar a estrutura
tree src/ --dirsfirst

# Resultado esperado:
# src/
# ├── agents/
# │   ├── claude/
# │   │   └── index.ts
# │   ├── ollama/
# │   │   └── index.ts
# │   ├── openrouter/
# │   │   └── index.ts
# │   └── index.ts
# ├── channels/
# │   ├── api/
# │   │   └── index.ts
# │   ├── telegram/
# │   │   └── index.ts
# │   └── index.ts
# ├── tools/
# │   ├── web-search/
# │   │   └── index.ts
# │   ├── file-read/
# │   │   └── index.ts
# │   ├── db-query/
# │   │   └── index.ts
# │   └── index.ts
# ... (remaining folders)

# Primeiro commit
git add .
git commit -m "feat: project scaffold with folder structure, barrel exports, and path aliases"