Rafael Santos

O diferencial

What makes it different

Arquitetura

Architecture

Engenharia

• Autenticação ponta a ponta. JWT assinado com RSA + endpoint JWKS; todos os serviços são resource servers independentes — o BFF não é a única porta, e cada serviço defende a própria visibilidade.
• Mapa por viewport. Consulta por bounding box com query nativa PostGIS, decimação de pontos preservando início e fim do percurso, e teto de trilhas por consulta.
• Ao vivo de verdade. Sessões transmitidas por STOMP sobre WebSocket, com autorização social (público / seguidores / amigos / privado) checada na assinatura do tópico.
• Vazamento de GPS eliminado. A consulta por bounding box filtrava visibilidade só no BFF; hoje o serviço de localização resolve os caminhos visíveis antes de devolver uma coordenada.
• Concorrência provada, não presumida. Corridas de contador resolvidas com lock pessimista na linha-pai e validadas com testes de 50 escritas simultâneas em Testcontainers.
• CI/CD por projeto, num monorepo. Um workflow do GitHub Actions por pasta: o commit que mexe num serviço testa e publica só ele. Docker multi-stage com usuário non-root, imagens no ghcr.io e migrations versionadas com Flyway.

Engineering

• Authentication end to end. RSA-signed JWT plus a JWKS endpoint; every service is an independent resource server — the BFF is not the only door, and each service defends its own visibility.
• Map by viewport. Bounding-box lookups with a native PostGIS query, point decimation that preserves the start and end of the route, and a ceiling on trails per query.
• Live for real. Sessions streamed over STOMP on WebSocket, with social authorisation (public / followers / friends / private) checked when the topic is subscribed.
• GPS leak closed. The bounding-box query used to filter visibility only at the BFF; today the location service resolves which paths are visible before returning a single coordinate.
• Concurrency proven, not assumed. Counter races solved with a pessimistic lock on the parent row and validated by tests with 50 simultaneous writes in Testcontainers.
• CI/CD per project, in a monorepo. One GitHub Actions workflow per folder: a commit that touches one service builds and ships only that service. Multi-stage Docker with a non-root user, images on ghcr.io and versioned migrations with Flyway.

Números

Numbers

Sistema de pins do produto

The product's pin system

Repositório

Repository

Dentro do código

Os cinco serviços seguem o mesmo esqueleto — controller → service → repository, com mapper traduzindo entidade e DTO, e auth e trace em todos, porque cada serviço se defende sozinho e cada requisição é rastreável ponta a ponta. O que muda de um para o outro é o que está abaixo.

Inside the code

The five services share the same skeleton — controller → service → repository, with mapper translating between entity and DTO, and auth and trace in all of them, because each service defends itself and every request stays traceable end to end. What changes from one to the next is below.

O ponto de partida

Where it starts

Arquitetura

Architecture

Decisões

• A transação muda de identidade. O provedor troca o ID de uma transação quando ela muda muito. A sincronização relê uma janela de dias e marca como apagada a que sumiu dela — em vez de duplicar o lançamento ou perdê-lo de vista.
• Dado sensível cifrado no banco. A descrição de cada transação é gravada com AES-256-GCM: um vazamento do banco de dados não conta onde a pessoa gasta dinheiro.
• Um BFF que conhece as telas. A home pede cinco coisas ao core em paralelo; a parte que falha volta marcada como indisponível e o resto aparece. Só uma home completa vai para o cache — senão o cache congelaria a tela no meio da primeira sincronização.
• O BFF não guarda segredo. O core assina os tokens (RS256) e publica a chave pública; o BFF a busca de lá. O identificador da chave é o thumbprint dela: com um identificador fixo e a chave em cache, o BFF recusava por 5 minutos os tokens de um core recém-reiniciado.
• Sessão sob medida para cada plataforma. No navegador, a renovação vive num cookie HttpOnly com proteção contra CSRF e a sessão cai por inatividade. No celular, o token fica no armazenamento seguro e o app pede biometria antes de mostrar saldo. No Windows, quem destrava é o Windows Hello.
• Instalável e atualizado sozinho. O CI gera o instalador do Windows a cada versão; o app lê o manifesto da release, confere o SHA-256 do arquivo e se atualiza sem a pessoa abrir o GitHub.

Decisions

• A transaction changes identity. The provider swaps a transaction's ID when it changes enough. Sync rereads a window of days and marks as deleted whatever vanished from it — instead of duplicating the entry or losing track of it.
• Sensitive data encrypted at rest. Every transaction description is stored with AES-256-GCM: a database leak doesn't tell anyone where the person spends their money.
• A BFF that knows the screens. The home screen asks the core for five things in parallel; a part that fails comes back flagged as unavailable and the rest still shows. Only a complete home goes into the cache — otherwise the cache would freeze the screen halfway through the first sync.
• The BFF holds no secret. The core signs the tokens (RS256) and publishes the public key; the BFF fetches it from there. The key id is the key's thumbprint: with a fixed id and the key cached, the BFF used to reject tokens from a freshly restarted core for 5 minutes.
• Sessions tailored to each platform. In the browser, renewal lives in an HttpOnly cookie with CSRF protection and the session ends on inactivity. On phones, the token sits in secure storage and the app asks for biometrics before showing any balance. On Windows, Windows Hello unlocks it.
• Installable, and updates itself. CI builds the Windows installer for every version; the app reads the release manifest, checks the file's SHA-256 and updates itself without the person ever opening GitHub.

Números

Numbers

Repositório

Repository

Dentro do código

Dois serviços e um app, no mesmo repositório. No core, cada módulo do Spring Modulith só conversa com os outros pela fachada pública deles — e um teste quebra se alguém atravessar a fronteira.

Inside the code

Two services and an app, in one repository. In the core, each Spring Modulith module only talks to the others through their public facade — and a test breaks if anyone crosses that boundary.

O diferencial

What makes it different

Arquitetura

Architecture

Decisões

• Uma loja nunca enxerga a outra. Todo documento carrega a loja, e os repositórios a leem do token — nunca de um parâmetro que o cliente possa trocar. Requisição sem loja falha. O isolamento é provado por teste contra um MongoDB de verdade, não contra um mock.
• Concorrência resolvida no banco, não na sorte. Um lote só muda por compare-and-set, com a quantidade e a situação esperadas. Dois caixas tirando do mesmo lote não vendem a mesma unidade: quem perde a disputa recebe 409 e a venda é refeita sozinha.
• Desfazer em vez de confirmar. Produto, entrada e venda feitos por engano podem ser desfeitos por 10 minutos, enquanto nenhuma unidade saiu. Um "tem certeza?" a cada bipe travaria a fila do caixa.
• Sessão que não se bifurca. O token de renovação é trocado por compare-and-set, e um token já usado que reaparece encerra todas as sessões — alguém guardou uma cópia. Por isso o front renova numa fila só, inclusive entre abas (Web Locks), e tolera o aparelho que perdeu a resposta no meio.
• Leitor USB não é teclado. Menos de 20 ms entre teclas ninguém digita: o front separa a rajada do leitor da digitação de gente, e devolve o campo ao valor anterior quando o bipe cai num campo com foco.
• O contrato é vigiado por teste. Os testes de HTTP fixam a lista de rotas abertas e a de rotas só do dono: uma rota nova que precise ser exceção quebra o teste até alguém acrescentá-la — de propósito.

Decisions

• One store never sees another. Every document carries its store, and repositories read it from the token — never from a parameter the client could change. A request without a store fails. The isolation is proven by tests against a real MongoDB, not a mock.
• Concurrency settled in the database, not by luck. A batch only changes through compare-and-set, with the expected quantity and state. Two tills taking from the same batch cannot sell the same unit: the loser gets a 409 and the sale retries on its own.
• Undo instead of confirm. A product, receipt or sale entered by mistake can be undone for 10 minutes, as long as no unit has left. An "are you sure?" on every scan would stall the checkout queue.
• Sessions that don't fork. The refresh token is swapped through compare-and-set, and a used token that shows up again ends every session — someone kept a copy. That's why the front end renews in a single queue, across tabs too (Web Locks), and tolerates a device that lost the response midway.
• A USB reader is not a keyboard. Nobody types with less than 20 ms between keys: the front end tells the reader's burst apart from a person typing, and restores a focused field to its previous value when a scan lands in it.
• The contract is guarded by tests. HTTP tests pin the list of open routes and of owner-only routes: a new route that needs to be an exception breaks the test until someone adds it — on purpose.

Números

Numbers

Repositórios

Repositories

Dentro do código

Quatro projetos em camadas, e o domínio não sabe onde os dados moram. Foi isso que permitiu trocar SQLite por MongoDB no meio do caminho tocando no domínio só para acrescentar a noção de loja.

Inside the code

Four layered projects, and the domain doesn't know where the data lives. That is what made it possible to swap SQLite for MongoDB midway, touching the domain only to add the notion of a store.

O pipeline

The pipeline

Decisões

• Vulkan em vez de CUDA, por motivo de produto. O pacote CUDA não traz as bibliotecas de runtime da NVIDIA: sem o Toolkit instalado ele falha em silêncio e cai para CPU dez vezes mais lento. Vulkan roda com o driver comum, serve placas de qualquer fabricante com um binário só e ocupa 116 MB contra 312 MB.
• RTF é a métrica errada. O mesmo modelo na mesma máquina mede de 1,2x a 13,7x só mudando o tamanho do buffer, porque o custo é quase todo fixo — o Whisper processa em janelas de 30 s preenchidas com silêncio. O que decide a viabilidade é o custo absoluto por passada contra o intervalo de reprocessamento.
• O gargalo era CPU, não GPU. Com o tradutor usando os quatro núcleos, o custo do reconhecedor mais que dobrou e passou de 187% do intervalo. Limitar a tradução a dois núcleos devolveu a folga — e, contra a intuição, deixou a própria tradução mais rápida: espalhar trabalho pequeno por muitos núcleos custa mais em coordenação do que rende.
• Senha do histórico é criptografia, não tela de bloqueio. Pedir senha só para abrir a janela deixaria o arquivo legível no bloco de notas. O conteúdo é cifrado com AES-256-GCM e chave derivada por PBKDF2 — e a consequência está escrita na tela: senha esquecida é histórico perdido, porque qualquer recuperação seria também uma porta de entrada.
• Medir em ritmo real, não em lote. A versão inicial da janela deslizante passava nos testes e travava as confirmações em falas longas. O defeito só apareceu alimentando áudio no ritmo de uma conversa e olhando quando cada trecho era confirmado, não o que ele continha.

Decisions

• Vulkan instead of CUDA, for a product reason. The CUDA package doesn't ship NVIDIA's runtime libraries: without the Toolkit installed it fails silently and falls back to a CPU path ten times slower. Vulkan runs on the ordinary driver, serves cards from any vendor with a single binary and takes 116 MB against 312 MB.
• RTF is the wrong metric. The same model on the same machine measures anywhere from 1.2x to 13.7x purely by changing the buffer size, because the cost is almost entirely fixed — Whisper processes in 30-second windows padded with silence. What decides viability is the absolute cost per pass against the reprocessing interval.
• The bottleneck was CPU, not GPU. With the translator using all four cores, the recogniser's cost more than doubled and went past 187% of the interval. Capping translation at two cores gave the headroom back — and, against intuition, made translation itself faster: spreading small work across many cores costs more in coordination than it returns.
• The history password is encryption, not a lock screen. Asking for a password merely to open the window would leave the file readable in a text editor. The content is encrypted with AES-256-GCM and a PBKDF2-derived key — and the consequence is stated on screen: a forgotten password means a lost history, because any recovery path would also be a way in.
• Measure at real pace, not in batch. The first version of the sliding window passed its tests and still stalled confirmations during long speech. The defect only showed up feeding audio at conversation pace and watching when each chunk was confirmed, not what it contained.

O pipeline

The pipeline

Decisões

• Monolito por escolha, não por preguiça. É um portal de leitura mantido por uma pessoa: um processo só custa menos, opera mais fácil e ainda cabe inteiro na cabeça. Os limites entre ingestão, curadoria, autoria e publicação estão nos pacotes, não em containers.
• Dois modelos, duas contas diferentes. Haiku faz o trabalho de volume e Opus só toca no que sobrou da peneira — o custo por matéria publicada é rastreado no próprio código.
• Sanitizar não é opcional. O conteúdo vem de feeds de terceiros direto para o HTML do portal: sem passar por Jsoup, isso é XSS servido em casa.
• Build que não exige Docker. Os testes de integração com Testcontainers vivem num sourceSet separado; check deliberadamente não depende deles.

Decisions

• A monolith by choice, not by laziness. It is a reading portal maintained by one person: a single process costs less, is easier to operate and still fits in one head. The boundaries between ingestion, curation, authoring and publishing live in packages, not in containers.
• Two models, two very different bills. Haiku does the volume work and Opus only touches what survived the sieve — the cost per published article is tracked in the code itself.
• Sanitising is not optional. Content arrives from third-party feeds and goes straight into the portal's HTML: without passing through Jsoup, that is XSS served at home.
• A build that doesn't require Docker. Testcontainers integration tests live in their own source set; check deliberately does not depend on them.

Stack

Dentro do código

É um monolito, mas não é uma pasta só: cada etapa do pipeline é um pacote de primeiro nível em com.web.newstech, com o próprio repositório e as próprias exceções. A fronteira que viraria um serviço em outro desenho aqui é a fronteira do pacote.

Inside the code

It is a monolith, but not a single folder: every stage of the pipeline is a top-level package in com.web.newstech, with its own repository and its own exceptions. The boundary that would be a service in another design is the package boundary here.

Os serviços

The services

Engenharia

• Os dois estilos, lado a lado. O BFF chama os serviços por REST, porque a resposta ao cliente é síncrona por natureza; a transação publica TransactionEvent num tópico Kafka próprio, porque quem reage a ela não precisa segurar essa resposta.
• Credencial não mora no código. Usuário e senha do SMTP vêm do ambiente (MAIL_USERNAME, MAIL_PASSWORD) e o remetente é injetado por configuração — repositório público não é lugar de segredo.
• Retry onde a falha é transitória. Spring Retry aplicado por AOP no ponto de integração: a tentativa é repetida sem poluir a regra de negócio com try/catch.
• Cobertura medida, não decorativa. JaCoCo em todos os serviços, com exclusão explícita de configuração, DTO, entidade e mapper — o número reflete lógica de negócio testada, não getter.
• Infra local sobe junto. Docker Compose declarado no projeto e integrado ao Spring Boot, então bootRun levanta o banco antes da aplicação.

Engineering

• Both styles, side by side. The BFF calls the services over REST, because the answer to the client is synchronous by nature; the transaction publishes TransactionEvent to its own Kafka topic, because whoever reacts to it doesn't need to hold that answer up.
• Credentials don't live in the code. SMTP user and password come from the environment (MAIL_USERNAME, MAIL_PASSWORD) and the sender is injected from configuration — a public repository is no place for a secret.
• Retry where the failure is transient. Spring Retry applied through AOP at the integration point: the attempt is repeated without littering business rules with try/catch.
• Coverage measured, not decorative. JaCoCo across the services, explicitly excluding configuration, DTOs, entities and mappers — the number reflects tested business logic, not getters.
• Local infra comes up with it. Docker Compose declared in the project and wired into Spring Boot, so bootRun starts the database before the application.

Stack

Repositórios

Repositories

Dentro do código

Quatro repositórios pequenos e propositalmente desiguais: o serviço que carrega o domínio tem camada completa, o que faz uma coisa só tem duas classes. Tamanho de serviço é consequência do que ele faz, não padrão a cumprir.

Inside the code

Four small and deliberately uneven repositories: the service carrying the domain has the full layering, the one that does a single thing has two classes. Service size is a consequence of what it does, not a standard to comply with.