Cifra

Cifra é uma aplicação full stack de gestão financeira pessoal.

O projeto permite registrar receitas e despesas, organizar lançamentos por categorias e acompanhar informações financeiras por meio de um dashboard.

Foi desenvolvido como projeto de portfólio com foco em arquitetura de software, segurança, qualidade de código, testes, observabilidade e práticas de engenharia aplicadas a sistemas financeiros.

Funcionalidades

• Autenticação e autorização de usuários
• Verificação de e-mail por código de uso único (fluxo de cadastro)
• Gestão de contas financeiras
• Cadastro e gerenciamento de categorias
• Registro de receitas e despesas
• Consulta e filtragem de transações
• Dashboard financeiro
• Resumos por período e categoria
• Controle de acesso baseado em papéis
• Isolamento de dados entre usuários
• Auditoria de operações relevantes
• Área administrativa
• Health checks e observabilidade da API

Arquitetura

O backend utiliza uma arquitetura de Modular Monolith, combinada com princípios de Clean Architecture e SOLID.

A aplicação é organizada por módulos de domínio, mantendo responsabilidades bem definidas e baixo acoplamento entre componentes.

Principais módulos:

• Auth
• Email Verification
• Users
• Accounts
• Categories
• Transactions
• Financial Summary
• Administration
• Audit

A autorização considera tanto o papel do usuário quanto a propriedade do recurso. Um usuário somente pode acessar contas e transações pertencentes a ele.

A área administrativa possui recursos específicos para gestão operacional, auditoria e observabilidade da plataforma.

Documentação arquitetural, decisões técnicas e diagramas estão disponíveis em docs/.

Stack

Backend

• NestJS
• TypeScript
• Prisma
• PostgreSQL
• REST API
• Swagger / OpenAPI

Frontend

• React
• Next.js
• TypeScript

Monorepo

• PNPM
• Turborepo

Infraestrutura

• Docker
• Neon PostgreSQL
• Google Cloud Compute Engine (e2-micro)
• Vercel
• GitHub Actions

Estrutura

cifra/
├── .github/
│   └── workflows/
├── apps/
│   ├── api/
│   └── web/
├── packages/
│   ├── ui/
│   ├── shared/
│   ├── eslint-config/
│   └── typescript-config/
├── docs/
│   ├── architecture/
│   ├── adr/
│   ├── security/
│   └── runbooks/
├── docker-compose.yml
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
└── turbo.json

Backend

A API é construída com NestJS e organizada como um Modular Monolith.

Suas principais responsabilidades incluem:

• autenticação
• autorização
• regras de negócio
• validação de entrada
• persistência
• auditoria
• observabilidade
• integração com o banco de dados

O Prisma é utilizado como ORM e o PostgreSQL como banco de dados principal.

A API possui um Dockerfile próprio em apps/api/Dockerfile, utilizado para gerar a imagem de produção.

Frontend

A aplicação web utiliza Next.js e React.

O frontend é responsável pela interface de autenticação, gestão financeira, lançamento de transações, consultas e visualização dos indicadores financeiros.

A comunicação com o backend ocorre por meio da API REST.

Em produção, o frontend é hospedado na Vercel.

Segurança

O projeto aplica práticas de segurança compatíveis com uma aplicação que manipula informações financeiras pessoais.

Entre os mecanismos utilizados estão:

• JWT
• Hash seguro de senhas
• RBAC
• Validação de entrada
• Controle de propriedade dos recursos
• Isolamento de dados entre usuários
• Auditoria de operações relevantes
• Logs sem informações sensíveis
• Configuração segura de variáveis de ambiente

A autorização não depende apenas do papel do usuário. Recursos financeiros também são validados quanto à sua propriedade antes de serem acessados ou modificados.

API

A API segue o padrão REST.

A documentação dos endpoints é disponibilizada através do Swagger / OpenAPI.

Em ambiente local:

http://localhost:3000/api/docs

Portas de desenvolvimento

O monorepo executa frontend e backend como aplicações independentes.

Serviço	Porta
Next.js	3001
NestJS API	3000
PostgreSQL	5432

O frontend utiliza:

http://localhost:3001

e a API:

http://localhost:3000/api/v1

Banco de dados

Durante o desenvolvimento local, o PostgreSQL é executado através do Docker Compose.

docker compose up -d

O arquivo docker-compose.yml está localizado na raiz do monorepo e é responsável pela infraestrutura local.

Em produção, o PostgreSQL utilizado pela API é hospedado no Neon.

As migrações do Prisma devem ser executadas a partir do workspace da API.

pnpm --filter api prisma migrate dev

Testes

O projeto possui diferentes níveis de testes:

• Unitários
• Integração
• E2E

As principais ferramentas utilizadas são:

• Vitest
• Supertest
• Playwright

Os testes são executados pelo pipeline de CI.

Desenvolvimento local

Pré-requisitos

• Node.js 24+
• PNPM
• Docker

Instalação

Na raiz do monorepo:

pnpm install

Configure os arquivos .env utilizando os respectivos .env.example disponíveis na raiz e nos aplicativos.

Configuração de e-mail (Gmail SMTP)

Para o envio real dos códigos de verificação de e-mail utilizando o Gmail:

1. Certifique-se de ter a Verificação em duas etapas ativada na sua conta Google.
2. Acesse a página de Senhas de app do Google.
3. No campo Nome do app, informe um identificador (ex.: Cifra Local) e clique em Criar.
4. O Google gerará uma senha de 16 caracteres com espaços (ex.: abcd efgh ijkl mnop). Copie e remova todos os espaços (ex.: abcdefghijklmnop).
5. Configure as variáveis no seu apps/api/.env:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=seu_email@gmail.com
SMTP_PASS=abcdefghijklmnop
EMAIL_FROM="Cifra <seu_email@gmail.com>"

Dica: Em ambiente local, se as variáveis SMTP_* não forem preenchidas, a aplicação não falhará — o código de 6 dígitos será exibido diretamente nos logs do terminal da API para você copiar e testar com facilidade.

Banco de dados

Inicie o PostgreSQL:

docker compose up -d

Execute as migrações:

pnpm --filter api prisma migrate dev

Desenvolvimento

Para iniciar frontend e backend:

pnpm dev

O Turborepo executará as aplicações simultaneamente:

Next.js  → http://localhost:3001
NestJS   → http://localhost:3000

Docker

O Docker Compose é utilizado para infraestrutura de desenvolvimento local.

O Dockerfile da API está localizado em:

apps/api/Dockerfile

A imagem da API pode ser construída a partir da raiz do monorepo:

docker build -f apps/api/Dockerfile .

O frontend não possui Dockerfile de produção, pois é hospedado diretamente na Vercel.

Deploy

A arquitetura de produção é composta por:

Vercel
└── Next.js

Google Cloud Compute Engine
└── Docker
    └── NestJS API

Neon
└── PostgreSQL

O frontend é publicado na Vercel.

A API é executada em uma instância Google Cloud Compute Engine e2-micro através de um container Docker.

O PostgreSQL de produção é hospedado no Neon.

O processo de build, testes e integração é automatizado através do GitHub Actions.

Documentação

A documentação complementar fica organizada em:

docs/
├── adr/
├── architecture/
├── runbooks/
└── security/

• adr/ — decisões arquiteturais relevantes
• architecture/ — arquitetura e estrutura do sistema
• runbooks/ — procedimentos operacionais
• security/ — definições relacionadas à segurança

Status

Projeto em desenvolvimento.

O objetivo atual é construir uma aplicação funcional de gestão financeira pessoal, aplicando práticas de engenharia utilizadas em sistemas profissionais de produção.

Autor

David Martins

Senior Software Engineer

Tecnologias principais: TypeScript, Node.js, NestJS, React, Next.js, PostgreSQL e arquitetura de sistemas.