Documentação Técnica Sinapse

Bem-vindo à documentação técnica do Sinapse. Este guia fornece informações detalhadas sobre arquitetura, instalação, configuração e manutenção do sistema.

Visão Geral da Arquitetura

O Sinapse é construído com uma arquitetura moderna e escalável:

Carregando diagrama...

Stack Tecnológica

Backend

Framework: FastAPI 0.104+
Runtime: Python 3.11+
ORM: SQLAlchemy 2.0 (Async)
Database: PostgreSQL 15+
Cache: Redis 7+

Infraestrutura

Container: Docker 24+
Orquestração: Kubernetes 1.28+
CI/CD: GitHub Actions
Monitoramento: Prometheus + Grafana
Logs: ELK Stack

Segurança

Autenticação: JWT (RS256)
Criptografia: AES-256 (dados em repouso)
TLS: 1.3+ (dados em trânsito)
Secrets: Variáveis de ambiente seguras

Requisitos do Sistema

Desenvolvimento

CPU: 4+ cores
RAM: 8GB+
Disco: 20GB+ SSD
OS: Linux/macOS/Windows (WSL2)

Produção

CPU: 8+ cores por nó
RAM: 16GB+ por nó
Disco: 100GB+ SSD (IOPS: 3000+)
Rede: 1Gbps+ dedicado

Guias Rápidos

Instalação Docker

Configure o ambiente em minutos

Arquitetura Detalhada

Entenda os componentes do sistema

Configuração

Variáveis e parâmetros do sistema

Desenvolvimento

Setup para desenvolvedores

Instalação Rápida

Docker Compose (Desenvolvimento)

# Clone o repositório
git clone https://github.com/sinapse/core-api.git
cd core-api

# Configure variáveis de ambiente
cp .env.example .env
# Edite .env com suas configurações

# Inicie os serviços
docker-compose up -d

# Execute migrações
docker-compose exec api alembic upgrade head

# Crie dados iniciais
docker-compose exec api python scripts/create_initial_data.py

# Acesse a API
curl http://localhost:8000/api/v1/health

Verificação da Instalação

# Status dos containers
docker-compose ps

# Logs da API
docker-compose logs -f api

# Teste de autenticação
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "senha": "admin123"}'

Arquitetura de Módulos

O Sinapse segue uma arquitetura modular limpa:

core_sinapse/
├── core/                   # Núcleo do sistema
│   ├── config.py          # Configurações centrais
│   ├── database.py        # Conexão com banco
│   ├── security.py        # Funções de segurança
│   └── permissions.py     # Sistema RBAC
│
├── modules/               # Módulos funcionais
│   ├── auth/             # Autenticação
│   ├── usuarios/         # Gestão de usuários
│   ├── agravos/          # Casos de doenças
│   └── noticias/         # Sistema de notícias
│
├── migrations/            # Migrações Alembic
├── scripts/              # Scripts utilitários
└── tests/                # Testes automatizados

Segurança em Camadas

1. Camada de Rede

Firewall com regras restritivas
DDoS protection (Cloudflare/AWS Shield)
SSL/TLS obrigatório
VPN para acesso administrativo

2. Camada de Aplicação

Autenticação JWT com rotação
Rate limiting por IP e usuário
Input validation em todos endpoints
CORS configurado restritivamente

3. Camada de Dados

Criptografia AES-256 em repouso
Backup criptografado
Auditoria de todos acessos
Anonimização de dados sensíveis

Padrões e Convenções

Código

Style Guide: PEP 8 + Black formatter
Type Hints: Obrigatórios (mypy strict)
Docstrings: Google style
Testes: Pytest com 80%+ cobertura

API

Versionamento: URL path (/v1, /v2)
Respostas: JSON com schema consistente
Erros: RFC 7807 (Problem Details)
Paginação: Cursor-based para grandes datasets

Banco de Dados

Naming: snake_case
PKs: UUIDs ou BigInt
Timestamps: UTC com timezone
Soft Delete: deleted_at timestamp

Monitoramento e Observabilidade

Métricas (Prometheus)

# Exemplo de métrica customizada
from prometheus_client import Counter, Histogram

api_requests = Counter(
    'api_requests_total',
    'Total API requests',
    ['method', 'endpoint', 'status']
)

request_duration = Histogram(
    'api_request_duration_seconds',
    'API request duration',
    ['method', 'endpoint']
)

Logs Estruturados

import structlog

logger = structlog.get_logger()

logger.info(
    "user_action",
    user_id=user.id,
    action="login",
    ip_address=request.client.host,
    user_agent=request.headers.get("user-agent")
)

Distributed Tracing

OpenTelemetry para rastreamento
Jaeger para visualização
Correlation IDs em todas requisições

CI/CD Pipeline

Carregando diagrama...

Ferramentas de Desenvolvimento

Essenciais

IDE: VS Code com extensões Python
API Client: Postman/Insomnia
DB Client: DBeaver/pgAdmin
Container: Docker Desktop

Debugging

# Configuração para debugging remoto
import debugpy

if settings.DEBUG:
    debugpy.listen(("0.0.0.0", 5678))
    print("Waiting for debugger attach...")
    debugpy.wait_for_client()