Pular para conteúdo

Backend

Python ≥ 3.11 (a imagem usa 3.12), FastAPI, SQLAlchemy 2 assíncrono + asyncpg, nats-py, clickhouse-connect/chdb, numpy, httpx, asyncssh, pyVmomi, ldap3, cryptography/argon2, anthropic. Todo o I/O é asyncio. Chamadas bloqueantes (chdb, ldap3, pyVmomi, smtplib, ansible-runner) rodam em asyncio.to_thread.

quantix.common

Módulo Responsabilidade Principais símbolos
config.py variáveis de ambiente QV_* (pydantic-settings, .env) Settings, get_settings() (lru_cache), resolved_master_key(), resolved_jwt_secret()
catalog.py catálogo canônico: tipos de objeto, relações, métricas (unidade, agregação, higher_is_worse, applies_to) ENTITY_TYPES, RELATION_KINDS, METRICS, Metric, catalog_dict()
models.py modelo relacional (ver ER) Tenant, User, Role, Device, Entity, Relation, Identifier, Finding, Health…
db.py engine e sessões get_engine(), session_scope() (serviços), get_session() (FastAPI), create_schema()
tsdb.py ClickHouse: DDL (nó único/cluster), backends HTTP com failover e chdb, retenção schema_statements(), MetricsStore, get_store(), pick_resolution()
query.py consultas analíticas parametrizadas MetricQuery (pydantic), QueryEngine.run(), modos timeseries/topn/latest/stat/heatmap/distribution
topology.py BFS do grafo com política de expansão neighborhood(session, root, depth, max_nodes), LAYER, FORWARD, BACKWARD
bus.py NATS JetStream connect(), ensure_streams(), consumer_config(), pack/unpack (msgpack)
settings_registry.py variáveis da GUI SettingDef, DEFS, REGISTRY, validate(), settings_cache
crypto.py Fernet, Argon2, tokens encrypt_json/decrypt_json, encrypt_str/decrypt_str, hash_password, new_token, hash_token
ids.py IDs determinísticos e normalização entity_id() (UUID5), normalize_wwn(), normalize_naa(), format_wwn()
notify.py canais de alerta send(channel, finding, settings), render_text()
logging.py log JSON setup_logging(service), JsonFormatter

quantix.collector

service.py (CollectorService: config, reconciliação, laços alinhados, tarefas, heartbeat), publisher.py (NatsPublisher com object store, HttpsPublisher), plugins/ (contrato em base.py, utilitários em _util.py, registro em __init__.py::_MODULES). Ver Coleta e Criando um plugin.

quantix.ingestor

service.py: metrics_loop (fetch de 256 mensagens; MetricsWriter valida o lote inteiro antes de acumular; flush em 250 mil linhas ou 2 s; ack após o insert, nak(5 s) em falha, term para mensagem inválida) e inventory_loop (uma mensagem por vez; baixa do object store, in_progress(), apply_snapshot, ack; nak(30 s) em falha). inventory.py::apply_snapshot: COPY → diff (config_changes) → merge de entidades → remoção lógica → identificadores → relações do coletor → metadados do dispositivo, tudo em uma transação.

quantix.engine

Módulo Função pública Ver
service.py Engine.tick(), _with_lock() (advisory lock), main() Engine
ratings.py run_ratings(), Thresholds.resolve(), level_for() ratings
capacity_models.py lookup(), controller_utilization(), port_capacity_mbps(), expected_latency_factor() idem
change_detection.py run_change_detection(), SERIES change detection
forecast.py run_forecast(), theil_sen(), r2() previsão
balance.py run_balance(), GROUPS balanceamento
config_rules.py run_config_rules() regras
correlator.py correlate(), RULES correlação
findings.py F (achado), FindingSink.add/commit(), fmt_bytes, fmt_num ciclo de vida
alerts.py dispatch() Alertas
applications.py run_applications(), app_criticality() aplicações
reports.py build_summary(), daily_summary() —

Adicionar uma regra de achado: crie a função no módulo do job (ou um novo job em Engine.tick), produza objetos F(rule, category, severity, title, detail, recommendation, entity_id=…, key=…, magnitude=…, evidence=…), chame sink.add() e, ao final, await sink.commit(). O FindingSink(session, rules={...}, grace=N) resolve automaticamente apenas os achados das regras informadas. Inclua a regra em Regras da engine e um teste em tests/integration/test_pipeline.py.

quantix.ai

providers.py (AnthropicProvider, OpenAICompatibleProvider, make_provider) e assistant.py (TOOLS, ToolRunner.t_<ferramenta>, Anonymizer, chat(), explain_finding()). Para adicionar uma ferramenta: declare-a em TOOLS (nome, descrição, JSON Schema) e implemente t_<nome> em ToolRunner, respeitando self._scope() (tenants) e self.anon (anonimização).

quantix.automation

worker.py: run_once() pega uma execução approved com FOR UPDATE SKIP LOCKED, monta inventário e extravars (_context: qv_target, qv_device, qv_device_username/password, qv_finding, itsm, parâmetros) e executa o playbook em diretório temporário isolado (ansible-runner, timeout 30 min, saída limitada a 200 mil caracteres). Para adicionar um runbook: crie automation/playbooks/<arquivo>.yml e uma entrada em api/bootstrap.py::PLAYBOOKS (chave, nome, descrição, risco, aprovação, tipos alvo, params_schema, que gera o formulário na GUI). Se precisar de contexto especial, adicione-o em _context.

quantix.api

Arquivo Conteúdo
main.py create_app(): middlewares (GZip, CORS fechado, cabeçalhos de segurança), handler de ValueError → 400, routers, lifespan (bootstrap + workers embutidos)
bootstrap.py schema, papéis padrão, tenant padrão, admin, coletor padrão, runbooks, dashboards de sistema (system_dashboards.py)
security.py PERMISSIONS, BUILTIN_ROLES, Principal, create_token/decode_token, current_principal, require(perm), current_collector
ldap_auth.py authenticate(), test_directory(), map_roles()
common.py audit(), entity_names(), page()
routers/ auth, admin, devices (coleta e endpoints de máquina), data, insights, workspace (dashboards e aplicações), ops (alertas e automação), ai, system

Adicionar um endpoint: escolha o router da área, declare o modelo pydantic de entrada, proteja com Depends(require("<permissão>")), aplique o escopo de tenant (p.tenant_ids() / p.tenant_slugs_for()), registre com audit() as alterações e devolva page() em listas paginadas. Depois rode python docs/gen_api.py --refresh e adicione a descrição em português em PT no gen_api.py.

quantix.tools

demo_seed.py (seed(days, arrays, hosts, step): dispositivos simulados + histórico) e admin.py (reset_admin(username)).