Documentação — onion-backend
Índice completo da documentação do projeto. O primeiro nível de .project/docs/ é um conjunto fechado: specs/, plans/, features/, learnings/, architecture/, guides/, reference/<escopo>/, rules/<escopo>/, mais os arquivos reservados README.md, RULES.md e modules.md.
Nome de arquivo e de pasta em inglês (snake_case); título, corpo e tabelas em português. Todo doc carrega certainty no frontmatter: high = veio do documento original ou de código verificado; medium = parcialmente reconstruído a partir do código; low = majoritariamente inferido.
| Categoria | Docs | O que vive aqui |
|---|---|---|
| specs | 47 | Mudanças planejadas ou executadas |
| plans | 2 | Passo-a-passo de implementação de uma spec |
| rules | 12 | Regras de negócio em Given/When/Then |
| reference | 6 | Como o sistema é: fluxos, APIs, contratos, modelos |
| learnings | 11 | Aprendizados retrospectivos de bug ou decisão |
| guides | 1 | How-to operacional |
As regras também têm um índice dedicado em RULES.md, ordenado por R-XXX.
features/ e architecture/ ainda não têm documentos neste repo.
specs
Mudanças planejadas ou executadas, nomeadas YYYYMMDDHHMMSS_short_name.md pelo timestamp do primeiro commit.
| Doc | Status | Descrição |
|---|---|---|
| 20260331175408_rename_master_to_main | done | Renomeia a branch principal de master para main em CI/CD e scripts de deploy |
| 20260408094751_python_stack_commons | in_progress | Cria a stack Python no .commons e migra o onion-backend para ela |
| 20260413000000_datadog_integration | done | Datadog Agent no dev via Docker e instrumentação com ddtrace |
| 20260414120000_k8s_infra_staging | done | Adiciona .infra/ com Terraform + Kustomize para deploy em Kubernetes |
| 20260417141500_migrate_staging_to_k8s | proposed | Substitui o deploy de staging por SSH pelo pipeline k8s |
| 20260419000000_database_url_readonly_default | in_progress | Torna DATABASE_URL readonly por padrão, com escrita via entrypoint |
| 20260506120000_default_habits | done | Hábitos pré-configurados por período do dia, exibidos no onboarding |
| 20260507160624_habit_streak_consistency | done | Streak, nível de consistência e totais diários nos endpoints de execução |
| 20260508155907_consistency_range_endpoint | done | GET /v1/habits/consistency com dias completos e % num intervalo |
| 20260513000000_fix_notification_deleted_habit | in_progress | Guard de deleted_at na query de notificações de hábito |
| 20260518000000_configure_tz_staging | proposed | Timezone America/Sao_Paulo nos pods e no banco de staging |
| 20260520111929_audio_notification_fk | proposed | FK de Audio para sua Notification agendada, para reagendamento isolado |
| 20260521000000_fix_deploy_onion_tasks | in_progress | Deriva conf/PID do supervisor dinamicamente do hostname |
| 20260522090219_reaction_lesson_comment | done | Campos comment/commented_at em ReactionLesson e PUT parcial |
| 20260522145722_notifications_platform_topics | done | Campo topics em PushDevices e service de subscrição em tópicos FCM |
| 20260522172251_send_to_platform_topic | in_progress | Campo platform_target em Notification para envio segmentado por SO |
| 20260525000000_auto_subscribe_device_topics | done | Inscrição automática do device nos tópicos FCM padrão no registro |
| 20260525120000_habit_reminder_notifications | in_progress | Até 4 lembretes de 2 em 2 horas, com variação de mensagem sorteada |
| 20260527000000_has_new_lessons_user_progress | proposed | has_new_lessons passa a considerar o progresso do usuário |
| 20260601000000_staging_db_conn_max_age | proposed | CONN_MAX_AGE=0 em staging contra esgotamento de conexões |
| 20260602000000_notification_10min_window | in_progress | Janela de 10 minutos no envio de notificações de hábito |
| 20260603092340_habit_description_in_dashboard | proposed | Expõe description no payload do dashboard de hábitos |
| 20260604120000_dedicated_queues_checkout_progress | proposed | Filas dedicadas para checkout e progresso, com prioridade entre elas |
| 20260605122000_conn_max_age | proposed | Conexões persistentes em production para reduzir churn no RDS Proxy |
| 20260608113017_expired_fcm_token | proposed | Marca PushDevices expirado e faz o app re-registrar na rotação de token |
| 20260612142912_progress_buffer_redis_flush | in_progress | Buffer de progresso no Redis com flush periódico via Celery beat |
| 20260615085522_staging_worker_progress_checkout_queues | in_progress | worker-progress em staging e rename de CELERY_DEFAULT_QUEUE |
| 20260615095011_habit_push_batch_fcm | done | Push de hábitos/lembretes direto ao FCM em lote via send_each |
| 20260615161050_celery_queues_runtime_cleanup | proposed | Remove o RUNTIME_MODE habits e renomeia para CELERY_QUEUES |
| 20260615180230_firebase_credentials_staging | in_progress | Cria o Secret firebase-credentials no cluster de staging |
| 20260617095609_recalculate_audio_duration_on_update | in_progress | Recalcula duração ao trocar o arquivo e sincroniza total_duration |
| 20260618095213_save_device_expire_duplicates | proposed | Expira push devices duplicados no registro de um device_id novo |
| 20260618154500_fix_audio_progress_funnel_counts | in_progress | Torna o funil de progresso de áudio cumulativo e consistente |
| 20260622174633_varredura_pattern_scan_backend | proposed | Admin da varredura de padrão e liberação por conclusão de aula-gate |
| 20260703114457_email_change_sync | proposed | Webhook de troca de e-mail do ibft-api para o onion-backend |
| 20260706235356_migrate_onion_backend_secrets_to_ward | proposed | Migra os secrets de SOPS para um único vault ward |
| 20260709175422_trail_courses | proposed | Model Trail para agrupar cursos em sequência ordenada |
| 20260710112204_progress_direct_persist_rate_limit | superseded | Progresso direto no banco, com buffer só sob rate limit |
| 20260710192955_migrate_infra_ci_to_eks | proposed | Provider kubernetes e CI de infra apontando para o EKS |
| 20260710235220_migrate_staging_cache_do_to_aws | done | Cache de staging da DO Valkey para AWS ElastiCache Serverless |
| 20260711003900_migrate_staging_db_do_to_aws | done | Banco de staging da DO para AWS Aurora Serverless v2 |
| 20260721194818_fix_migrate_ci | proposed | Move o migrate para o CI e remove os init containers wait-migrate |
| 20260723094615_unsubscribe_topics_on_device_expire | done | Unsubscribe dos tópicos FCM ao expirar um device |
| 20260806102829_migrate_production_to_eks | proposed | Production para o EKS com Aurora e ElastiCache na ibft-vpc |
| 20260821160901_staging_quorum_queues_global_qos | in_progress | Declara as filas de staging como quorum para o Celery desligar o global QoS |
| 20260826112801_trial_journey_block_reservation | proposed | Reserva dos emails da régua de trial em blocos de 200 por query |
| 20260902151259_admin_email_change_warning | proposed | Confirmação com aviso ao alterar o email do usuário no dashboard |
| 20260915090842_email_change_account_merge | done | Merge das duas contas quando a troca de e-mail aponta para um e-mail já usado |
plans
Passo-a-passo de implementação. spec: no frontmatter aponta para a spec correspondente, ou null quando não há.
| Doc | Spec | Descrição |
|---|---|---|
| 20260302175328_habits_api | — | Oito fases do módulo de micro hábitos, uma por endpoint |
| 20260512172815_audio_journey | — | Sete passos da jornada de áudios, de models ao endpoint diário |
rules
Regras de negócio em Given/When/Then. Índice ordenado por ID em RULES.md.
| ID | Doc | Escopo |
|---|---|---|
| R-001 | lesson_progress_direct_synchronous_persist | engagements |
| R-002 | journey_sequence_for_new_user | audios |
| R-003 | journey_locked_below_ninety_percent | audios |
| R-004 | journey_advances_next_day_after_completion | audios |
| R-005 | journey_relisten_does_not_regress | audios |
| R-006 | journey_transition_after_last_audio | audios |
| R-007 | daily_audio_outside_journey | audios |
| R-008 | audio_outside_journey_is_free_daily_content | audios |
| R-009 | journey_position_endpoint | audios |
| R-010 | notification_model_point_in_time_only | notifications |
| R-011 | habit_notification_gate | notifications |
| R-012 | user_trial_converted_at_on_checkout_approval | trials |
| R-015 | trial_state_in_auth_endpoints | trials |
| R-016 | trial_lesson_unlock | trials |
| R-017 | trial_course_unlock | trials |
| R-021 | trial_journey_emails | trials |
| R-022 | email_change_merges_existing_account | accounts |
reference
Como o sistema é: fluxos, contratos de API, modelos de dados.
| Doc | Escopo | Certainty | Descrição |
|---|---|---|---|
| daily_audio_journey | audios | high | Jornada de áudios diários: models, state machine, push diário e configuração |
| habits_api | habits | medium | Contrato dos endpoints de hábitos, execuções, consistência e defaults |
| default_habits | habits | high | Hábitos pré-configurados por período do dia e fluxo de onboarding |
| platform_topics | notifications | high | Tópicos FCM por plataforma, campo topics e envio segmentado |
| habit_push_notifications | notifications | high | Push de hábitos/lembretes em lote, gate is_notified e ondas de lembrete |
| database_url | infrastructure | medium | Contrato do DATABASE_URL, secrets readonly/fullaccess e pressão de conexões |
learnings
Aprendizados retrospectivos, nomeados <escopo>_short_name.md.
| Doc | Escopo | Descrição |
|---|---|---|
| audio_duration_recalc_on_file_change | audios | Recálculo de duração depende da troca de arquivo; snapshots de progresso precisam sincronizar |
| audio_push_notification_single_source | audios | Dois produtores para o mesmo push diário geravam notificação duplicada |
| engagements_flush_de_progresso_nao_registrado | engagements | Task fora do __init__.py do pacote não é registrada pelo autodiscovery |
| habits_notification_for_deleted_habit | habits | Join por FK não passa pelo manager de soft-delete |
| notifications_fcm_send_each_batch_expired_tokens | notifications | send_each não levanta exceção em falha parcial; expiração vem do BatchResponse |
| infrastructure_do_to_aurora_staging_migration | infrastructure | Gotchas da migração para Aurora: publicly_accessible, dois providers, cold start |
| infrastructure_do_to_elasticache_staging_migration | infrastructure | ElastiCache não tem acesso público — VPC peering é obrigatório |
| infrastructure_pgbouncer_connection_pool | infrastructure | Banco pequeno esgotava slots de conexão sem pooling (histórico) |
| infrastructure_sqs_countdown_visibility_timeout | infrastructure | countdown ≥ visibility_timeout no SQS causa execução duplicada |
| infrastructure_rabbitmq_quorum_queues_global_qos | infrastructure | Quorum queue rejeita global QoS; o Celery decide pelo que declarou, não pelo tipo real |
| infrastructure_dd_trace_disabled_staging_via_settings | infrastructure | Terraform de staging quebrado; DD_TRACE_ENABLED desligado via settings em vez de configmap |
guides
How-to operacional.
| Doc | Descrição |
|---|---|
| server_monitoring_setup | Instalar o Node Exporter num servidor ARM64 e registrá-lo no Prometheus |