Este projeto é uma aplicação backend construída com FastAPI, projetada para gerenciar usuários, papéis, permissões e transações em um sistema baseado em Role-Based Access Control (RBAC). A API suporta autenticação via JWT, autorização granular, auditoria de ações e integração com um banco de dados usando SQLAlchemy como ORM.
Este projeto utiliza o FastAPI para servir Agentes inteligentes utilizando o CrewAI
Sobre o Projeto • Tecnologias • Requisitos • Arquitetura • Como Usar • Como Contribuir • Licença
Este projeto é uma aplicação backend construída com FastAPI, projetada para gerenciar usuários, papéis, permissões e transações em um sistema baseado em Role-Based Access Control (RBAC). A API suporta autenticação via JWT, autorização granular, auditoria de ações e integração com um banco de dados usando SQLAlchemy como ORM.
- Autenticação: Login de usuários com geração de tokens JWT.
- Autorização: Controle de acesso baseado em papéis e permissões.
- Gerenciamento de Usuários: Criação, atualização, listagem e exclusão de usuários.
- Gestão de Papéis e Permissões: Atribuição de papéis a usuários e permissões a papéis.
- Auditoria: Registro de informações de auditoria (usuário, IP, data de criação/atualização).
- Testes Automatizados: Suporte a testes com pytest e cobertura de código.
O projeto é estruturado para ser modular, escalável e seguir boas práticas de desenvolvimento, como separação de responsabilidades e uso de ferramentas modernas de desenvolvimento Python.
Este projeto utiliza as seguintes tecnologias e ferramentas:
- Linguagem: Python 3.12
- Framework: FastAPI - Framework web para construção de APIs.
- ORM: SQLAlchemy - Mapeamento objeto-relacional.
- Banco de Dados: SQLite - Banco de dados leve e embarcado.
- Gerenciador de Dependências: Uv Astral - Gerenciamento de dependências e ambientes virtuais.
- Migrações: Alembic - Gerenciamento de migrações de banco de dados.
- Testes: pytest com pytest-cov para cobertura de testes.
- Linting e Formatação: Ruff, Blue, e isort para manter o código limpo.
- Autenticação: python-jose para JWT e bcrypt para hash de senhas.
Para rodar ou contribuir com o projeto, você precisará das seguintes ferramentas instaladas:
| Ferramenta | Versão | Instalação (Linux/macOS) |
|---|---|---|
| Python | 3.12 | asdf install python 3.12 ou similar |
| UV | Latest | `curl -LsSf https://astral.sh/uv/install.sh |
| Git | Latest | sudo apt install git (Linux) ou brew install git (macOS) |
| SQLite | Latest | Geralmente pré-instalado, ou sudo apt install sqlite3 |
Nota: Recomendamos o uso do asdf para gerenciar versões do Python. Consulte o arquivo .python-version para a versão exata do Python utilizada.
A estrutura do projeto é organizada para promover modularidade e facilitar a manutenção. Abaixo está a organização dos arquivos e diretórios:
FastAPI-CrewAI/
├── apps/ # Aplicações do monólito
│ ├── core/ # 🔐 API REST com RBAC
│ │ ├── api/ # Endpoints da API
│ │ │ ├── assignment/ # 👥 Designações (usuário-papel)
│ │ │ ├── authentication/ # 🔑 Autenticação (login, JWT)
│ │ │ ├── authorization/ # ✅ Autorizações (papel-transação)
│ │ │ ├── role/ # 🏷️ Gerenciamento de papéis
│ │ │ ├── transaction/ # 📋 Gerenciamento de transações
│ │ │ ├── user/ # 👤 Gerenciamento de usuários
│ │ │ └── text_processing/ # 🔄 Processamento de texto (bridge para IA)
│ │ ├── database/ # 🗄️ Configuração SQLAlchemy
│ │ ├── models/ # 📊 Modelos ORM (User, Role, etc.)
│ │ ├── utils/ # 🛠️ Utilitários (segurança, configs)
│ │ └── startup.py # 🚀 Inicialização FastAPI
│ │
│ ├── ia/ # 🤖 Serviço de Agentes IA
│ │ ├── agents/ # 🧠 Definição dos agentes CrewAI
│ │ ├── api/ # 🌐 Endpoints específicos da IA
│ │ │ └── chat/ # 💭 Chat com agentes
│ │ ├── models/ # 📈 Modelos específicos da IA
│ │ ├── services/ # ⚙️ Serviços da IA
│ │ │ └── rag_service.py # 🔍 RAG com LangChain
│ │ └── tools/ # 🔧 Ferramentas para agentes
│ │ └── rag_search_tool.py # 🔎 Ferramenta de busca RAG
│ │
│ └── packpage/ # 📦 Utilitários compartilhados
│ ├── base_model.py # 🏗️ Modelo base com auditoria
│ ├── llm.py # 🧮 Configuração LLM (Groq)
│ └── generic_controller.py # 🎮 Controller genérico CRUD
│
├── migrations/ # 🔄 Migrações Alembic
├── scripts/ # 📜 Scripts de automação
├── seeds/ # 🌱 Dados iniciais
├── tests/ # 🧪 Testes automatizados
│ ├── factory/ # 🏭 Factories para testes
│ └── conftest.py # ⚙️ Configuração pytest
├── DOCS/ # 📚 Documentação
│ ├── PERMISSIONS.MD # 🔐 Guia RBAC
│ ├── FLUXOGRAMA.MD # 🔄 Fluxos da aplicação
│ └── DEPLOYMENT.md # 🚀 Deploy em produção
├── .devcontainer/ # 🐳 Configuração dev container
├── .secrets/ # 🔒 Arquivos sensíveis
├── .env-semple # 📋 Template de configuração
├── alembic.ini # ⚙️ Configuração Alembic
├── uv.lock # 🔒 Lockfile dependências
└── pyproject.toml # 📦 Configuração projetoO projeto utiliza um modelo de dados baseado em RBAC, com as seguintes entidades principais:
- User: Representa os usuários do sistema.
- Role: Papéis que definem permissões.
- Assignment: Associa usuários a papéis.
- Transaction: Operações do sistema (ex.: criar, listar, excluir).
- Authorization: Associa papéis a transações, definindo permissões.
- Core ↔ IA: Comunicação via modelos compartilhados no banco
- Auditoria Unificada: Todos os serviços usam
AbstractBaseModel - Autenticação Centralizada: JWT válido para ambos os serviços
- RAG Integration:
rag_service.pyindexa documentos,rag_search_tool.pyrealiza buscas
- Repository Pattern:
GenericControllerpara CRUD - Factory Pattern: Factories em
tests/factory/para dados de teste - Middleware Pattern:
AuthorizationMiddlewarepara interceptação - Service Layer: Serviços específicos em
apps/ia/services/
Para informações técnicas detalhadas sobre o projeto, consulte os documentos específicos:
- Diagrama ER: DOCS/MODELS.png - Visualização completa das entidades e seus relacionamentos no banco de dados.
- Guia Completo: DOCS/PERMISSIONS.MD - Documentação detalhada sobre:
- Como um usuário novo ganha permissões
- Como criar novas permissões no sistema
- Estrutura hierárquica de roles
- Cenários práticos de uso
- Sistema de segurança e validações
- Fluxo Técnico: DOCS/FLUXOGRAMA.MD - Mapeamento completo dos fluxos da aplicação:
- Pontos de entrada (endpoints)
- Pontos de decisão (middlewares e validações)
- Pontos de saída (respostas e persistência)
- Agrupamentos naturais do sistema
- Guia Completo: DOCS/DEPLOYMENT.md - Documentação detalhada sobre:
- Configuração do ambiente de produção com Docker
- Setup com PostgreSQL e Docker Compose
- Comandos para gerenciamento de containers
- Backup e restauração do banco de dados
- Considerações de segurança e performance
- Troubleshooting de problemas comuns
Siga os passos abaixo para configurar e executar o projeto localmente.
git clone https://github.com/jvras58/fastapi-crewai
cd fastapi-crewaiEste repositório esta organizando em um devcontainer. E para instacia-lo no VSCODE é recomendado as seguintes configurações:
- Name: Remote Development
- Id: ms-vscode-remote.vscode-remote-extensionpack
- Description: An extension pack that lets you open any folder in a container, on a remote machine, or in WSL and take advantage of VS Code's full feature set.
- Version: 0.25.0
- Publisher: Microsoft
- VSCode Marketplace Link: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack
É obrigatório ter o Docker Engine já instalado e cunfigurado. Para mais informações de como instalar o Docker Engine em seu SO, ver em:
- Instruções para instalação do Docker Engine: Ver o link
- Com o pack de extenções instalado,
- Realize o clone/fork deste repositório,
- Abra o diretorio deste repositorio no VSCODE como um projeto,
- Use o Comando Dev Containers: Reopen in Container da paleta de comandos do VSCODE. (F1, Ctrl+Shift+P).
Depois da compilação do container o VSCode abrirá o repositório em um ambiente encapsulado e executando diretamente de dentro do container como configurado nas definições do /.devconainer.
Crie o arquivo .env baseado no modelo fornecido:
cp .env-semple .envEdite o arquivo .env com as configurações adequadas. Exemplo:
DB_URL="sqlite:///database.db"
SECURITY_ALGORITHM="HS256"
SECURITY_ACCESS_TOKEN_EXPIRE_MINUTES=30
Crie o diretório .secrets e adicione o arquivo SECURITY_API_SECRET_KEY com um valor seguro:
mkdir .secrets
echo "SUA_CHAVE_SECRETA_AQUI" > .secrets/SECURITY_API_SECRET_KEYAtive o ambiente virtual e instale as dependências com o UV:
uv sync
uv installEntre no ambiente virtual: source activate_env.sh
Execute as migrações para criar as tabelas no banco de dados: A) aplique as migrations existentes:
alembic upgrade headb) Suba os seedings de RBAC e de usuario admin
task setup_dbInicie o servidor FastAPI com o comando:
task runA API estará disponível em:
- URL Local: http://localhost:8000
- Documentação Interativa: http://localhost:8000/api/v1/docs (Swagger UI)
- Documentação Alternativa: http://localhost:8000/api/v1/redoc (ReDoc)
Para rodar os testes automatizados e verificar a cobertura:
task testO relatório de cobertura será gerado em htmlcov/index.html.
Contribuições são sempre bem-vindas! Para contribuir com o projeto:
- Fork o repositório
- Crie uma branch para sua feature (
git checkout -b feature/nova-feature) - Commit suas mudanças (
git commit -m 'Adiciona nova feature') - Push para a branch (
git push origin feature/nova-feature) - Abra um Pull Request
- Siga as convenções de código estabelecidas
- Escreva testes para novas funcionalidades
- Mantenha a documentação atualizada
- Use mensagens de commit descritivas
Este projeto está licenciado sob a MIT License. Veja o arquivo LICENSE para mais detalhes.
Se tiver dúvidas ou sugestões, entre em contato:
- Autores: jvras jvras58@gmail.com