Este repositorio implementa uma aplicacao fullstack para o desafio final de Arquitetura de Software: uma API REST no padrao MVC que disponibiliza dados de um dominio para parceiros de uma empresa de vendas on-line.
Os dominios de negocio sao User, Product e Order. A aplicacao entrega
backend, frontend, persistencia, documentacao OpenAPI, diagramas arquiteturais e
binario compilado em um unico projeto Bun. A escolha foi intencional: manter baixa friccao de
execucao, demonstrar arquitetura real e preservar um caminho claro de evolucao
sem introduzir infraestrutura desnecessaria para o escopo do desafio.
Stack real:
- Runtime e build: Bun.
- API: Elysia REST.
- Contratos: Zod.
- Documentacao: OpenAPI em
/api/openapi. - UI: React servida pelo mesmo processo Bun.
- Roteamento frontend: React Router.
- Persistencia: SQLite via
bun:sqlite. - Testes:
bun:testcom banco migrado em memoria. - Build final: executavel em
dist/software-arch.
Entregaveis principais:
- Checklist final:
docs/final-submission.md. - Arquitetura:
docs/architecture.md. - API:
docs/api.md. - Implantacao local/binario:
docs/deployment.md. - Diagramas fonte:
docs/diagrams/*.mmdedocs/diagrams/drawio/*.drawio. - Diagramas renderizados:
docs/diagrams/exports/*.svgedocs/diagrams/exports/*.png. - Explicacao detalhada dos diagramas:
docs/diagrams/*.md.
Os diagramas abaixo sao renderizados em PNG para leitura direta no README. Os
arquivos .mmd continuam como fonte editavel e os .svg continuam disponiveis
para inspecao com zoom.
Mostra o sistema no ambiente externo: avaliador, usuario comum, admin, sistemas
parceiros, browser, runtime Bun, API REST, UI React, OpenAPI e SQLite. A
explicacao detalhada fica em
docs/diagrams/c4-context.md.
Mostra os containers internos do processo Bun: Bun.serve, roteadores HTTP,
frontend React, API Elysia, modulos MVC, auth guard, error handler, OpenAPI e
SQLite. A explicacao detalhada fica em
docs/diagrams/c4-container.md.
Mostra o contrato de cada feature module: routes, schema, controller, service,
repository, mapper, errors e model. Tambem explicita como auth, user,
product e order seguem o padrao. A explicacao detalhada fica em
docs/diagrams/mvc-modules.md.
O projeto roda como um unico processo HTTP:
Cliente/UI
-> Bun.serve
-> /api/* -> Elysia API
-> outras rotas -> React UIO backend fica em src/api e segue MVC por modulo. A UI fica em src/app e
consome dados somente via src/app/services/api-client.ts. src/server.ts e o
entrypoint unico usado tanto no desenvolvimento quanto no build compilado.
Estrutura principal:
src/
server.ts
routes/
api-router.ts
frontend-router.ts
api/
app.ts
config/
database/
modules/
auth/
user/
product/
order/
shared/
app/
components/
entrypoints/
pages/
admin/orders/
orders/
products/
services/
styles/
tests/
app/
helpers/
http/
modules/
docs/
architecture.md
api.md
deployment.md
diagrams/Cada dominio tem seu proprio conjunto de arquivos:
src/api/modules/<domain>/
<domain>.model.ts
<domain>.schema.ts
<domain>.repository.ts
<domain>.service.ts
<domain>.controller.ts
<domain>.routes.ts
<domain>.errors.ts
<domain>.mapper.tsEsse formato deixa o MVC explicito por feature, reduz acoplamento entre dominios e evita um MVC global onde todos os controllers, services e repositories ficam espalhados por tipo tecnico.
Controllers recebem entrada ja validada pela rota/schema, chamam services e devolvem resposta HTTP. Regra de negocio nao deve morar em controller.
Services concentram regra de negocio e orquestracao. Eles nao guardam estado entre requests, o que melhora previsibilidade, concorrencia e testabilidade.
Repositories encapsulam SQL, prepared statements e conversao entre linhas do SQLite e modelos de dominio. A persistencia fica substituivel sem reescrever controller, schema ou UI.
Schemas Zod definem entrada e saida publica. Eles sao a primeira barreira contra payload invalido e impedem validacao duplicada em controllers.
Mappers convertem modelo interno para DTO publico. Esse padrao evita vazamento
de campos sensiveis como passwordHash.
Rotas protegidas usam JWT via guard HTTP. O usuario autenticado entra no fluxo como contexto de request, nao por leitura manual repetida em cada controller.
Erros de dominio sao convertidos para respostas HTTP padronizadas no boundary compartilhado. Isso reduz branching nos controllers e mantem contratos de erro previsiveis.
O banco evolui por migrations SQL versionadas em src/api/database/migrations.
Novas migrations precisam ser registradas em src/api/database/migrate.ts; o
runner nao faz discovery automatico por diretorio.
UI e API compartilham processo para simplificar entrega e reduzir latencia
local, mas a UI nao acessa banco nem regra de negocio. O contrato entre frontend
e backend continua sendo HTTP em /api.
Request HTTP
-> src/server.ts
-> src/routes/api-router.ts
-> src/api/app.ts
-> <domain>.routes.ts
-> <domain>.controller.ts
-> <domain>.service.ts
-> <domain>.repository.ts
-> SQLiteNo caminho inverso, o repository devolve modelo interno, service aplica regra de negocio, mapper/schema garantem resposta publica e o error handler transforma falhas conhecidas em status HTTP consistente.
Instale dependencias:
bun installSuba em modo desenvolvimento:
bun run devURLs locais:
- UI:
http://localhost:3000 - Health:
http://localhost:3000/api/health - OpenAPI UI:
http://localhost:3000/api/openapi - OpenAPI JSON:
http://localhost:3000/api/openapi/json
Variaveis de ambiente:
| Variavel | Default | Papel |
|---|---|---|
PORT |
3000 |
Porta HTTP do processo Bun |
DATABASE_URL |
data/software-arch.db |
Caminho do SQLite file-backed |
JWT_SECRET |
development-secret-change-me |
Segredo HMAC para JWT |
NODE_ENV |
development |
Ambiente de runtime |
Rodar em porta isolada:
PORT=3131 DATABASE_URL=/tmp/software-arch.db bun run devCredencial administrativa inicial:
email: super@admin.app
password: 123456Essa conta e reservada para bootstrap administrativo: ela autentica, mas nao
aparece em /api/users, /api/users/count nem /api/users/search. Essas
colecoes tambem excluem o usuario autenticado na request.
Login via HTTP:
curl -X POST http://localhost:3000/api/auth/login \
-H "content-type: application/json" \
-d '{"email":"super@admin.app","password":"123456"}'Use o accessToken retornado no corpo da resposta como header de autorizacao:
Authorization: Bearer <accessToken>Validacao minima antes de concluir mudancas de codigo:
bun run typecheck
bun testValidacao para mudancas de build/runtime:
bun run typecheck
bun test
bun run build
bun run start:binaryValidacao para mudancas documentais:
git diff --check
git status --shortTestes por camada:
tests/http: contrato HTTP, status codes, auth e OpenAPI.tests/modules: services e repositories por dominio.tests/app: boundaries do frontend, rotas, sessao e validacoes de UI.tests/helpers/test-db.ts: cria SQLite:memory:migrado para testes.
Executar um arquivo especifico:
bun test tests/http/users.routes.test.tsProduto e gerenciado por admin:
curl -X POST http://localhost:3000/api/products \
-H "authorization: Bearer <accessToken>" \
-H "content-type: application/json" \
-d '{"sku":"SKU-001","name":"Teclado mecanico","quantity":12}'Pedido e criado por usuario autenticado com um ou mais itens:
curl -X POST http://localhost:3000/api/orders \
-H "authorization: Bearer <accessToken>" \
-H "content-type: application/json" \
-d '{"items":[{"productId":"<product-id>","quantity":2}]}'Regras principais:
- pedido inicia como
em_andamento; - itens duplicados do mesmo produto sao consolidados;
- criacao de pedido so efetiva se houver estoque suficiente;
- criacao e cancelamento alteram estoque em transacao SQLite;
- usuario cancela apenas pedido proprio em andamento;
- admin altera status apenas para
em_andamentoouconcluido; - pedido
canceladonao retorna para outro status.
O comando correto do projeto e:
bun run buildNao use bun build sozinho para este repo. bun build e o bundler CLI de
baixo nivel e exige entrypoints; bun run build executa scripts/build.ts com
o pipeline correto de frontend, Tailwind e compile.
Depois do build:
PORT=3131 DATABASE_URL=/tmp/software-arch.db bun run start:binary
curl http://localhost:3131/api/healthFluxo recomendado:
- Atualize ou crie schemas em
src/api/modules/<domain>/<domain>.schema.ts. - Adicione regra de negocio em
src/api/modules/<domain>/<domain>.service.ts. - Adicione acesso SQL em
src/api/modules/<domain>/<domain>.repository.ts. - Exponha a operacao em
src/api/modules/<domain>/<domain>.controller.ts. - Registre a rota em
src/api/modules/<domain>/<domain>.routes.ts. - Se houver novo payload/resposta publica, garanta mapper seguro em
src/api/modules/user/user.mapper.ts. - Cubra o contrato com testes em
tests/httpe a regra emtests/modules. - Atualize
docs/api.mdquando o contrato HTTP mudar.
Regra pratica: controller nao decide regra de negocio, repository nao conhece HTTP e UI nao replica validacao de backend.
Crie um modulo com o mesmo formato de user, product e order:
src/api/modules/product/
product.model.ts
product.schema.ts
product.repository.ts
product.service.ts
product.controller.ts
product.routes.ts
product.errors.ts
product.mapper.tsDepois:
- Registre as rotas em
src/api/app.ts. - Crie migration SQL se houver persistencia nova.
- Registre a migration em
src/api/database/migrate.ts. - Adicione testes de repository/service/HTTP.
- Atualize OpenAPI implicito via schemas/rotas.
- Atualize
docs/api.md,docs/architecture.mde diagramas se o dominio alterar a arquitetura descrita.
O frontend deve usar apenas src/app/services/api-client.ts para chamadas HTTP.
Nao coloque fetch, token JWT ou regra de negocio do backend diretamente em
page/component.
Fluxo recomendado:
- Adicione metodo tipado no API client.
- Reuse
src/app/services/auth-session.tspara token/sessao. - Mantenha validacoes de formulario locais apenas para UX imediata.
- Trate erro de API tipado quando o backend devolver erro de dominio.
- Cubra comportamento com testes em
tests/app.
Reduz boilerplate, startup e custo operacional. O trade-off e menor portabilidade para ambientes Node tradicionais e menor maturidade de ecossistema do que Express/Fastify em operacoes corporativas antigas.
Simplifica deploy, elimina CORS interno e reduz latencia local. O custo e acoplar ciclo de release e escala da UI com a API. Para o desafio, isso melhora avaliacao e reduz superficie operacional.
Remove dependencia externa e deixa SQL visivel. O limite natural e escrita concorrente: SQLite e excelente para baixa/media escrita e leitura local rapida, mas nao e a escolha certa para varias instancias escrevendo no mesmo banco. No fluxo de pedidos, transacoes curtas debitam/devolvem estoque para reduzir tempo de lock.
Mais arquivos do que um CRUD monolitico, mas melhor coesao por dominio e melhor leitura arquitetural. Evita overengineering de Clean Architecture completa sem abrir mao de boundaries reais.
Reduz I/O por request e simplifica escala horizontal da camada HTTP. O custo e revogacao: logout global, bloqueio imediato e rotacao avancada exigiriam denylist, refresh tokens ou sessao server-side.
Centraliza validacao e documentacao de payload. O custo e manter schemas como fonte de verdade; duplicar validacao em controller ou UI degrada o desenho.
Use este desenho quando:
- O objetivo e demonstrar MVC, REST, OpenAPI e persistencia real.
- O produto e pequeno/medio, ferramenta interna ou API de parceiro com baixa concorrencia de escrita.
- O dominio precisa de catalogo, estoque e pedidos basicos sem pagamento/fiscal.
- A prioridade e deploy simples, latencia baixa e codigo facil de avaliar.
- O time quer evoluir por troca de repository/persistencia antes de redesenhar toda a aplicacao.
Evite ou reavalie quando:
- Houver necessidade real de multiplas instancias escrevendo no mesmo banco.
- A UI precisar deploy independente da API.
- O dominio exigir transacoes complexas, auditoria forte ou historico temporal.
- Estoque exigir ledger completo de movimentacoes ou reserva temporaria.
- Auth exigir revogacao imediata, refresh tokens, RBAC granular ou SSO.
- Observabilidade, tracing distribuido e metricas por rota forem requisitos de producao desde o primeiro release.
O primeiro gargalo provavel e escrita SQLite, nao Elysia. O runtime e stateless
na camada de service/controller, mas o banco continua tendo limite de
single-writer. WAL e busy_timeout ajudam, mas nao transformam SQLite em banco
multi-writer distribuido.
Priorize:
- Paginacao e limite maximo em
GET /api/users,/api/products,/api/orderse/api/admin/orders. - Ordenacao explicita e indices alinhados aos filtros.
- Payloads menores e DTOs especificos por caso de uso.
- Prepared statements em todo caminho quente.
- Medicao de latencia p50/p95 por rota.
- Medicao de tempo de query por repository.
Quando volume ou concorrencia justificarem:
- Migrar repositories para Postgres mantendo service/controller estaveis.
- Adicionar paginacao cursor-based para listas grandes.
- Trocar busca
LIKEpor FTS ou search engine conforme requisito. - Introduzir refresh tokens/denylist se revogacao de auth virar requisito.
- Separar deploy da UI se release independente trouxer valor real.
- Adicionar logs estruturados, request id, metricas e tracing no boundary HTTP e repository.
O ponto central: preservar o contrato de dominio e trocar infraestrutura por necessidade medida, nao por preferencia arquitetural.



