google-calendar-sync

O Google Calendar Sync é um serviço auto-hospedado que mantém um calendário de destino sincronizado como uma projeção de um calendário de origem. Cada regra observa exatamente um calendário de origem e gerencia exatamente um calendário de destino, e origem e destino podem pertencer a identidades Google diferentes. O projeto é explicitamente rotulado como pré-alfa: a arquitetura, o motor de sincronização, a API autenticada, o adaptador Google e a interface Web formam uma primeira fatia vertical funcional, mas testes de resistência com contas reais e uma revisão de prontidão para produção ainda não foram concluídos, portanto recomenda-se usar calendários de teste e backups. Pontos-chave de design descritos no README: - Regras direcionais: uma origem, um destino, com comportamento autoritativo da origem. Edições no destino, projeções ausentes e cancelamentos na origem são reparados durante a sincronização e a reconciliação. - Padrões de privacidade: novas regras usam por padrão uma projeção de Disponibilidade; a cópia de detalhes é opcional e nunca copia participantes, identidade do organizador, dados de conferência, anexos ou convites. - Ativação segura: uma regra precisa passar por uma pré-visualização sem efeitos colaterais antes de poder ser habilitada. - Implantação autocontida: SQLite, agendamento, API e interface Web rodam como um único serviço leve, distribuído como imagem Docker e serviço Compose para linux/amd64 e linux/arm64. - Sem telemetria: uma instalação funcional se comunica apenas com as APIs Google necessárias para a sincronização e com qualquer endpoint de notificação que o operador configurar. As capacidades listadas incluem eventos com horário e de dia inteiro, séries recorrentes, alterações e cancelamentos de ocorrências únicas; políticas de apenas disponibilidade ou cópia de detalhes com inclusão de dia inteiro por regra; polling incremental a cada cinco minutos mais Sync Now manual; uma passagem diária de reconciliação completa mais Reconcile Now com relatório de desvios; prevenção de loops via metadados privados de origem gerenciada; chaves de operação estáveis, persistência de cursor por último, backoff de retentativas e falhas de regra isoladas; uma visualização autenticada de Atividade com deduplicação e entrega opcional de incidentes por SMTP ou webhook; uma senha de administrador local com credenciais OAuth do Google criptografadas; e temas claro/escuro. A configuração exige um projeto no Google Cloud com a Calendar API habilitada, um cliente OAuth 2.0 de aplicativo Web e o URI de redirecionamento exato http://localhost:8000/api/v1/oauth/google/callback. Segredos locais são configurados por meio de um arquivo .env, incluindo uma chave mestra de 256 bits que criptografa as credenciais Google armazenadas com AES-256-GCM. O README observa que perder a chave mestra torna ilegíveis as credenciais das contas conectadas, e que implantações hospedadas em LAN precisam de tratamento especial porque o Google rejeita URIs de redirecionamento em HTTP simples que não sejam localhost. Comportamento de sincronização: a primeira execução lê eventos de origem terminando não antes de 30 dias antes da execução, observa o destino e registra os tokens incrementais do Google para ambos os endpoints. Execuções posteriores consomem ambos os feeds de mudanças, de modo que edições ou exclusões apenas no destino são reparadas sem varreduras completas. Para cada evento de origem relevante, o domínio escolhe Create, Update, Delete, Ignore ou Conflict; identidade ou propriedade ambíguas não são adivinhadas. Os cursores avançam somente depois que um lote é totalmente bem-sucedido, e as gravações no provedor carregam chaves de operação estáveis para que as retentativas não dupliquem projeções. Notas de privacidade e segurança: títulos, descrições e locais de eventos são processados em memória e não armazenados no SQLite nem em entradas de auditoria; os mapeamentos retêm IDs do provedor, revisões e uma impressão digital não reversível; desconectar uma conta descarta as credenciais armazenadas sem excluir regras, mapeamentos ou projeções gerenciadas; gravações no Google usam sendUpdates=none; a interface Web e a API operacional exigem a sessão do administrador local, enquanto /health permanece público e mínimo. A arquitetura é um monólito modular com fronteiras de portas e adaptadores; o domínio de sincronização não tem dependências de FastAPI, SQLite, SDK do Google, React, OAuth ou Docker. O desenvolvimento do backend usa Python 3.12 e FastAPI; o frontend usa Node.js 22+, React, TypeScript, Vite e Tailwind CSS. As verificações de qualidade incluem ruff, mypy, pytest com piso de 80% de cobertura, typecheck/lint/test/build do frontend e builds Docker multiplataforma. O Google Calendar é o único provedor na versão inicial; Outlook e CalDAV são descritos como possibilidades arquiteturais, não recursos suportados. O projeto tem como alvo a versão 0.1.0 sob a Licença MIT.