TasksOrg — POC

POC de um app de organização de tarefas (diárias, semanais, anuais) com timer Pomodoro, inspirado no Notion. Objetivo desta etapa: validar a arquitetura multiplataforma (web, desktop e, no futuro, mobile) e deixar o pipeline de DevOps (CI) já configurado desde o início do projeto.

Stack

• Monorepo: pnpm workspaces + Turborepo para orquestrar build/lint/test/typecheck entre os pacotes, com cache incremental.
• Linguagem: TypeScript em 100% do código.
• Web: Next.js 14 (App Router) + React 18.
• Desktop: Electron 32, reaproveitando a mesma lógica de negócio.
• Lógica compartilhada: pacote @tasksorg/core, sem nenhuma dependência de UI — é usado tanto pela web quanto pelo desktop.
• Testes: Vitest no pacote core.
• Containers: Docker + Docker Compose — o app web roda em container tanto em desenvolvimento (com bind mount) quanto em produção (imagem multi-stage).
• CI/CD: GitHub Actions (.github/workflows/ci.yml). Kubernetes entra numa próxima etapa, para orquestrar o deploy dessas imagens.

Tudo em JavaScript/TypeScript, como decidido pelo grupo — isso permite compartilhar lógica, tipos e (no futuro) até componentes de UI entre as plataformas.

Estrutura do monorepo

TasksOrganization/
├── apps/
│   ├── web/        → Next.js (roda no navegador)
│   │   ├── Dockerfile      → imagem de PRODUÇÃO (multi-stage)
│   │   └── Dockerfile.dev  → imagem de DESENVOLVIMENTO (usada com bind mount)
│   └── desktop/     → Electron (empacota a web/lógica num app nativo)
├── packages/
│   └── core/         → Regras de negócio compartilhadas (tasks + pomodoro)
├── docker-compose.yml → sobe o app web em desenvolvimento (bind mount)
├── .github/workflows/ → pipeline de CI/CD com GitHub Actions
├── turbo.json
├── pnpm-workspace.yaml
└── package.json

Por que um monorepo?

Porque o core do projeto é rodar em várias plataformas com o mesmo comportamento. Colocar tudo em um único repositório com pacotes compartilhados evita duplicar regra de negócio (tipos de tarefa, lógica do pomodoro, etc.) em cada plataforma — e o Turborepo garante que só se rebuilda o que mudou.

packages/core

Contém, sem nenhuma dependência de React/DOM/Electron:

• task.ts — modelo de Task (escopo diário/semanal/anual, status, prioridade) e um TaskStore em memória.
• pomodoro.ts — uma máquina de estados PomodoroTimer (foco → pausa curta → pausa longa), agnóstica de como o tempo é avançado (quem consome chama tick()).

Isso é o que a Web e o Desktop importam e usam da mesma forma — é a prova de conceito de que dá pra compartilhar lógica de verdade entre as plataformas.

Como rodar

Pré-requisitos: Node 20+ e pnpm (corepack enable já resolve).

Overrides de segurança do pnpm. O projeto fixa o pnpm 9.12 (packageManager), que lê os overrides de package.json (pnpm.overrides). O pnpm 10+ lê só os de pnpm-workspace.yaml e avisa que ignorou o package.json: com um pnpm global mais novo, esse aviso é esperado e inofensivo. Ao alterar um override, mude os dois arquivos; o CI confere com node scripts/check-pnpm-overrides.mjs.

pnpm install

# roda tudo (lint, typecheck, test, build) em todos os pacotes
pnpm build
pnpm test
pnpm lint
pnpm typecheck

# desenvolvimento
pnpm --filter @tasksorg/web dev       # Next.js em http://localhost:3000
pnpm --filter @tasksorg/desktop dev   # builda e abre a janela do Electron

Testes E2E (Playwright)

pnpm --filter @tasksorg/web exec playwright install chromium   # uma vez

# só as telas (sem API): o teste de sincronização é pulado
pnpm test:e2e

# suíte completa, com API e PostgreSQL
docker compose up -d --wait postgres
export DATABASE_URL=postgresql://tasksorg:<senha do .env>@localhost:<porta>/tasksorg_test
export E2E_API_URL=http://localhost:3001 NEXT_PUBLIC_API_URL=http://localhost:3001
pnpm test:e2e

• O pnpm test:e2e builda web e API; com E2E_API_URL definido, o Playwright sobe a API sozinho e reaproveita uma que já esteja rodando (como no CI).
• NEXT_PUBLIC_API_URL entra no build do web: sem ela, o teste de sincronização falha mesmo com a API no ar.
• A porta do PostgreSQL aparece em docker compose port postgres 5432. O banco tasksorg_test é criado uma vez com docker compose exec postgres psql -U tasksorg -d tasksorg -c "CREATE DATABASE tasksorg_test".

O que já foi validado nesta POC

• packages/core com 13 testes unitários passando (tarefas + pomodoro).
• apps/web builda em modo produção (next build) e serve a página de verdade (testado localmente com next start).
• apps/desktop compila (tsc + bundle do renderer com esbuild) e a janela do Electron sobe sem erros de JS (validado em modo headless com Xvfb, que é como muitos CIs testam Electron; no Windows/macOS de vocês vai abrir normalmente com interface gráfica).
• Lint, typecheck, test e build passam localmente com os mesmos comandos que o pipeline de CI usa.
• docker-compose.yml tem sintaxe validada (docker compose config).
• Docker/Jenkins ainda não foram testados de ponta a ponta — o ambiente onde essa POC foi montada bloqueia acesso ao Docker Hub, então não deu pra buildar as imagens nem subir os containers por aqui. O primeiro teste real disso precisa ser feito na sua máquina (ou de algum colega). Veja a seção "Docker" abaixo com o passo a passo — e me chama se algo quebrar.

Docker

O app web roda em container de duas formas diferentes:

Desenvolvimento (com bind mount)

apps/web/Dockerfile.dev + docker-compose.yml fazem um bind mount da pasta do projeto pra dentro do container: você edita o código no VSCode, normalmente, e o container "enxerga" a mudança na hora — sem rebuildar nada.

This is the beginning of the README. Read the rest at the original. Read the full README ↗