How desenvolvweb/basic-front-boilerplate works
Tipo e propósito do projeto (o que o diagrama precisa “contar”)
Pelo README e pela árvore de arquivos, isto é um boilerplate front-end estático para estudos/testes, com:
• HTML + JS + Sass (SCSS)
• Parcel como build tool (dev server + bundling + hot reload + build para dist/)
• Estrutura de CSS baseada em ITCSS (camadas 01-settings … 99-utilities)
• Sem backend, sem banco, sem API própria. O “sistema” aqui é o pipeline de build + entrega dos assets no browser.
Seu diagrama, portanto, deve representar principalmente:
Fluxo de build/release (source → Parcel build → dist/ → publicação/artefato)
3) Arquitetura interna de assets (entrypoints HTML/JS/SCSS e como dependem dos partials e recursos img/, font/)
Entrypoints (pontos de entrada)
• index.html (entry principal carregado pelo browser / Parcel)
• js/index.js (entry principal do JS)
• style/index.scss (entry principal de estilo; importa todos os partials ITCSS)
Camadas de estilo (ITCSS)
Diretórios:
• style/01-settings/* (tokens: cores, tipografia, sizing, z-index, breakpoints…)
• style/02-tools/* (mixins/functions/helpers: ex _v.scss, _color.scss)
• style/04-elements/* (tags HTML: form, list, typography…)
• style/05-objects/* (padrões de layout/abstrações sem “skin”)
• style/06-components/* (componentes visuais)
• style/99-utilities/* (classes utilitárias, overrides)
Isso é uma “sub-arquitetura” importante: no diagrama, você pode representar como uma pilha/camadas alimentando o bundle CSS final.
Assets estáticos
• img/ e font/ (referenciados por HTML/CSS/JS; Parcel trata URLs e empacota)
Tooling e automação
• package.json, package-lock.json (scripts start, build; dependências Parcel/Sass etc.)
• .github/workflows/release.yml (pipeline de release no GitHub Actions)
• .husky/*, commitlint.config.js (qualidade/guard rails no commit)
• .editorconfig, .prettierrc, .stylelintrc, .hintrc (format/lint/hints)
• .nvmrc (versão Node recomendada)
> Observação: a pasta dist/ não aparece na árvore porque é gerada no build.
Interações e relações (setas do diagrama)
As relações centrais são de dependência/compilação e fluxo de entrega:
Desenvolvimento (runtime local)
• Dev (VSCode) altera index.html, js/index.js, style/index.scss e partials
• npm start → Parcel Dev Server:
• resolve imports (JS e SCSS)
• compila SCSS → CSS
• faz bundling/transforms
• serve index.html e assets
• injeta/ativa hot reload
• Browser consome via http://localhost:1234
Build (artefato)
• npm run build → Parcel Build
• gera bundles otimizados (hash/minify, etc.)
• output em dist/ (HTML/CSS/JS/assets prontos para publicar)
CI/Release (se quiser incluir)
• Push/tag/trigger → GitHub Actions (release.yml)
• instala deps
• roda build
• publica release/artefatos (dependendo do workflow)
Qualidade no ciclo de commit
• git commit → Husky commit-msg → Commitlint valida mensagem
• git commit → Husky pre-commit → (possíveis linters/formatters; mesmo que não esteja explícito no README, o hook existe)
Diagrama de Contexto / Container (C4-Container simplificado)
Mostra: Developer → Node/npm → Parcel → Browser → dist/ → (GitHub Actions/Release)
Diagrama de Componentes (dentro do “Front-end Source”)
Mostra: entrypoints e camadas ITCSS + assets.
Se você preferir 1 diagrama só, use duas raias horizontais:
• Lane: Dev-time
• Lane: Build/CI-time
E um bloco interno detalhando os sources.
Componentes principais para virar “caixas”
Sugestão de caixas (separando o máximo possível, sem overthink):
• Developer workstation
• Editor/IDE
• Git
• Node.js + npm (usa .nvmrc)
• Source code (repo)
• index.html
• js/index.js
• style/index.scss
• style/* (ITCSS layers)
• img/, font/
• Toolchain
• Parcel Dev Server (hot reload)
• Parcel Build (bundler)
• Sass compiler (implícito via Parcel; pode ser sub-caixa dentro de Parcel)
• Runtime
• Browser (consumindo localhost:1234)
• Build Output
• dist/ (site estático)
• Automation / Governance
• GitHub Actions (.github/workflows/release.yml)
• Husky hooks (.husky/*)
• Commitlint / Stylelint / Prettier / Webhint configs
Setas (data flow / dependency flow)
Use setas com verbos:
• Developer → “edits” → Source files
• npm start → “runs” → Parcel Dev Server
• Parcel Dev Server → “serves + HMR” → Browser
• style/index.scss → “imports” → 01-settings … 99-utilities
• img/font → “referenced by” → HTML/CSS/JS → “bundled into” → dist/
• npm run build → “produces” → dist/
• GitHub Actions → “runs build” → dist/ artifacts/release
Padrões/princípios arquiteturais que devem aparecer explicitamente
• Separation of concerns por tipo de asset: HTML vs JS vs SCSS vs assets
• Build pipeline zero-config (Parcel como orquestrador)
• ITCSS layering: represente como camadas ordenadas; isso é “a arquitetura” mais importante do projeto
• Dev feedback loop: hot reload (um loop de atualização do browser)
Labels
• Use nomes iguais aos do repo: index.html, js/index.js, style/index.scss, style/01-settings, etc.
• Para tooling: “Parcel (Dev Server)” e “Parcel (Build)”.
Setas direcionais
• Dependências: seta sólida
• Artefatos gerados: seta com label “outputs”
• Feedback loop (HMR): seta tracejada de volta do Parcel para o Browser (ou Browser ↔ Parcel)
Cores/formatos (sugestão)
• Azul: runtime (Browser)
• Verde: sources (HTML/JS/SCSS/assets)
• Laranja: build tools (Parcel/Sass)
• Roxo: automação/CI (GitHub Actions, hooks)
• Formas diferentes:
• Retângulos: componentes
• Cilindro (opcional): dist/ como “artefato/armazenamento”
• Documento: entrypoints (HTML/JS/SCSS) se quiser destacar
Um “template” de diagrama (o que você literalmente desenharia)
Topo (atores e execução):
• Developer → (git + npm) → Parcel Dev Server → Browser
• Developer → npm run build → Parcel Build → dist/
Centro (sources):
• index.html → references → js/index.js + style/index.scss
• style/index.scss → imports → 01-settings → 02-tools → 03-generics → 04-elements → 05-objects → 06-components → 99-utilities
• img/ + font/ → referenced by → HTML/CSS/JS
Base (automação):
• GitHub Actions (release.yml) → checkout → npm ci → npm run build → release artifacts (e/ou upload)
Checklist final para “best/most accurate”
• [ ] index.html, js/index.js, style/index.scss aparecem como entrypoints
• [ ] ITCSS está representado em camadas e na ordem correta
• [ ] Parcel aparece em dois modos: Dev Server e Build
• [ ] dist/ aparece como output do build
• [ ] img/ e font/ aparecem como assets empacotados
• [ ] Husky/commitlint e configs de lint/format aparecem como “governance”
• [ ] GitHub Actions (release.yml) aparece como pipeline de release (se aplicável ao seu público)
Se você desenhar com esse nível de decomposição, o diagrama fica fiel ao repositório e comunica claramente que o “sistema” aqui é um boilerplate front-end + pipeline de build/qualidade, não uma aplicação distribuída com backend.