Skip to content

Estrutura do Projeto

Este documento descreve a estrutura de diretórios e arquivos do projeto API de Gerenciamento de Carros.

Visão Geral da Estrutura

car_api/
├── .env                           # Variáveis de ambiente
├── .gitignore                     # Arquivos ignorados pelo Git
├── alembic.ini                    # Configuração do Alembic
├── car.db                         # Banco de dados SQLite (gerado automaticamente)
├── mkdocs.yml                     # Configuração da documentação MkDocs
├── poetry.lock                    # Lock file do Poetry
├── pyproject.toml                 # Configuração do projeto e dependências
├── README.md                      # Documentação inicial do projeto
├── car_api/                       # Código-fonte principal
│   ├── __init__.py                # Inicialização do pacote
│   ├── app.py                     # Ponto de entrada da aplicação FastAPI
│   ├── core/                      # Componentes centrais
│   │   ├── __init__.py
│   │   ├── database.py            # Configuração do banco de dados
│   │   ├── security.py            # Funções de segurança e autenticação
│   │   └── settings.py            # Configurações da aplicação
│   ├── models/                    # Modelos do SQLAlchemy
│   │   ├── __init__.py
│   │   ├── base.py                # Classe base para modelos
│   │   ├── cars.py                # Modelos relacionados a carros e marcas
│   │   └── users.py               # Modelo de usuário
│   ├── routers/                   # Rotas da API
│   │   ├── __init__.py
│   │   ├── auth.py                # Rotas de autenticação
│   │   ├── brands.py              # Rotas de marcas
│   │   ├── cars.py                # Rotas de carros
│   │   └── users.py               # Rotas de usuários
│   └── schemas/                   # Esquemas Pydantic para validação
│       ├── __init__.py
│       ├── auth.py                # Esquemas de autenticação
│       ├── brands.py              # Esquemas de marcas
│       ├── cars.py                # Esquemas de carros
│       └── users.py               # Esquemas de usuários
├── docs/                          # Documentação do projeto (criado por este processo)
│   ├── index.md                   # Página inicial da documentação
│   ├── prerequisites.md           # Requisitos do sistema
│   ├── installation.md            # Instruções de instalação
│   ├── configuration.md           # Configuração do projeto
│   ├── guidelines.md              # Diretrizes e padrões
│   ├── structure.md               # Esta página (estrutura do projeto)
│   ├── api-endpoints.md           # Documentação dos endpoints
│   ├── system-modeling.md         # Modelagem do sistema
│   ├── authentication.md          # Autenticação e segurança
│   ├── development.md             # Processo de desenvolvimento
│   ├── testing.md                 # Procedimentos de teste
│   ├── deployment.md              # Processo de deploy
│   ├── contributing.md            # Diretrizes de contribuição
│   └── release-notes.md           # Notas de versão
├── migrations/                    # Migrações do banco de dados (gerado pelo Alembic)
│   ├── README
│   ├── env.py
│   ├── script.py.mako
│   └── versions/                  # Histórico de migrações
├── tests/                         # Testes automatizados
│   ├── __init__.py
│   ├── conftest.py                # Configurações de teste
│   ├── test_auth.py               # Testes de autenticação
│   ├── test_brands.py             # Testes de marcas
│   ├── test_cars.py               # Testes de carros
│   └── test_users.py              # Testes de usuários
└── venv/                          # Ambiente virtual (se criado manualmente)

Descrição Detalhada dos Diretórios e Arquivos

Raiz do Projeto

  • .env: Arquivo contendo variáveis de ambiente sensíveis (não versionado)
  • .gitignore: Lista de arquivos e diretórios ignorados pelo Git
  • alembic.ini: Arquivo de configuração do Alembic para migrações de banco de dados
  • car.db: Arquivo do banco de dados SQLite (gerado automaticamente)
  • mkdocs.yml: Configuração para geração da documentação com MkDocs
  • poetry.lock: Lock file que garante dependências consistentes
  • pyproject.toml: Arquivo principal de configuração do projeto Python, incluindo dependências
  • README.md: Documentação inicial do projeto

Diretório car_api/

Contém o código-fonte principal da aplicação:

car_api/app.py

Ponto de entrada da aplicação FastAPI. Define os roteadores e configurações iniciais.

Subdiretório core/

Componentes centrais da aplicação:

  • database.py: Configuração do motor de banco de dados SQLAlchemy e função para obter sessões
  • security.py: Funções para autenticação, autorização, hashing de senhas e manipulação de JWT
  • settings.py: Configurações da aplicação usando Pydantic Settings

Subdiretório models/

Modelos de dados SQLAlchemy:

  • base.py: Classe base para todos os modelos
  • cars.py: Modelos para Carro e Marca, incluindo enums para tipo de combustível e transmissão
  • users.py: Modelo para Usuário

Subdiretório routers/

Definições de rotas da API:

  • auth.py: Endpoints para autenticação (login, refresh token)
  • brands.py: Endpoints para gerenciamento de marcas
  • cars.py: Endpoints para gerenciamento de carros
  • users.py: Endpoints para gerenciamento de usuários

Subdiretório schemas/

Esquemas Pydantic para validação de dados:

  • auth.py: Esquemas para autenticação (login, token)
  • brands.py: Esquemas para marca (criação, atualização, resposta pública)
  • cars.py: Esquemas para carro (criação, atualização, resposta pública)
  • users.py: Esquemas para usuário (criação, atualização, resposta pública)

Diretório docs/

Contém a documentação do projeto em formato Markdown, organizada conforme os requisitos do MkDocs.

Diretório migrations/

Contém os scripts de migração gerados pelo Alembic para gerenciamento de esquema de banco de dados.

Diretório tests/

Contém os testes automatizados da aplicação:

  • conftest.py: Configurações e fixtures compartilhados para testes
  • test_*.py: Arquivos de teste específicos para cada componente da API

Convenções de Nomenclatura

Diretórios

  • Usam snake_case para nomes de diretórios
  • São nomeados de forma descritiva e consistente

Arquivos Python

  • Usam snake_case para nomes de arquivos
  • Terminam com extensão .py
  • São nomeados de acordo com sua funcionalidade principal

Classes

  • Usam PascalCase para nomes de classes
  • São nomeadas de forma clara e descritiva

Funções e Variáveis

  • Usam snake_case para nomes de funções e variáveis
  • São nomeadas de forma clara e descritiva

Extensibilidade

A estrutura do projeto foi projetada para ser modular e extensível:

  • Novos endpoints podem ser adicionados criando novos arquivos em routers/
  • Novos modelos podem ser adicionados em models/
  • Novos esquemas podem ser adicionados em schemas/
  • A lógica de negócios pode ser encapsulada em módulos adicionais em core/

Essa separação clara de responsabilidades facilita a manutenção e expansão da aplicação.