# desenvolvweb/basic-front-boilerplate architecture

> Architecture diagram of the GitHub repository desenvolvweb/basic-front-boilerplate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/desenvolvweb/basic-front-boilerplate
- Repository: https://github.com/desenvolvweb/basic-front-boilerplate

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD

  %% =========================
  %% Actors / Environment
  %% =========================
  Dev["Developer"]:::actor
  IDE["Editor / IDE"]:::actor
  Git["Git"]:::tool
  NodeNpm["Node.js + npm"]:::tool
  Browser["Browser (localhost:1234)"]:::runtime

  %% =========================
  %% Source (Repo)
  %% =========================
  subgraph "Repository (Source Code)"
    HTML["index.html (HTML entrypoint)"]:::entry
    JS["js/index.js (JS entrypoint)"]:::entry
    SCSS["style/index.scss (SCSS entrypoint)"]:::entry

    subgraph "Styles (ITCSS layers)"
      S01["01-settings (tokens)"]:::itcss
      S01i["_index.scss (settings aggregator)"]:::itcssIndex

      S02["02-tools (mixins/functions)"]:::itcss
      S02i["_index.scss (tools aggregator)"]:::itcssIndex

      S03["03-generics (normalize/a11y)"]:::itcss
      S03i["_index.scss (generics aggregator)"]:::itcssIndex

      S04["04-elements (base elements)"]:::itcss
      S04i["_index.scss (elements aggregator)"]:::itcssIndex

      S05["05-objects (layout patterns)"]:::itcss
      S05i["_index.scss (objects aggregator)"]:::itcssIndex

      S06["06-components (UI components)"]:::itcss
      S06i["_index.scss (components aggregator)"]:::itcssIndex

      S99["99-utilities (utilities/overrides)"]:::itcss
      S99i["_index.scss (utilities aggregator)"]:::itcssIndex
    end

    subgraph "Static Assets"
      IMG["img/ (images)"]:::asset
      FONT["font/ (fonts)"]:::asset
    end
  end

  %% =========================
  %% Toolchain
  %% =========================
  subgraph "Toolchain (Parcel orchestrates bundling)"
    Start["npm start"]:::cmd
    Build["npm run build"]:::cmd

    ParcelDev["Parcel (Dev Server)"]:::build
    ParcelBuild["Parcel (Build)"]:::build
    Sass["Sass compiler (via Parcel)"]:::buildInner
  end

  %% =========================
  %% Output / Delivery
  %% =========================
  Dist[("dist/ (static site artifact)")]:::artifact

  %% =========================
  %% Automation / Governance
  %% =========================
  subgraph "Automation / Governance"
    subgraph "CI / Release"
      GHA["GitHub Actions (release.yml)"]:::ci
      ReleaseCfg["Release config (.releaserc.json)"]:::ci
    end

    subgraph "Git Hooks"
      Husky["Husky (.husky/)"]:::gov
      HookPre["pre-commit hook"]:::gov
      HookMsg["commit-msg hook"]:::gov
      Commitlint["Commitlint (config)"]:::gov
    end

    subgraph "Lint / Format / Hints (configs)"
      Prettier["Prettier (.prettierrc)"]:::lint
      PrettierIgnore["prettierignore"]:::lint
      Stylelint["Stylelint (.stylelintrc)"]:::lint
      StylelintIgnore[".stylelintignore"]:::lint
      Webhint["Webhint (.hintrc)"]:::lint
      EditorCfg[".editorconfig"]:::lint
      PostCSS["PostCSS (.postcssrc)"]:::lint
    end

    Pkg["package.json (scripts/deps)"]:::cfg
    Lock["package-lock.json"]:::cfg
    Nvm[".nvmrc (Node version pin)"]:::cfg
  end

  %% =========================
  %% Relationships (Dev loop)
  %% =========================
  Dev -->|"edits"| IDE
  IDE -->|"updates"| HTML
  IDE -->|"updates"| JS
  IDE -->|"updates"| SCSS
  Dev -->|"uses"| Git
  Dev -->|"runs"| NodeNpm

  NodeNpm -->|"reads"| Nvm
  NodeNpm -->|"reads"| Pkg
  NodeNpm -->|"installs"| Lock

  NodeNpm -->|"executes"| Start
  Start -->|"runs"| ParcelDev

  ParcelDev -->|"serves+HMR"| Browser
  Browser -.->|"hot-reload feedback"| ParcelDev

  %% Entrypoint dependencies
  HTML -->|"references"| JS
  HTML -->|"references"| SCSS
  IMG -->|"referenced-by"| HTML
  IMG -->|"referenced-by"| SCSS
  IMG -->|"referenced-by"| JS
  FONT -->|"referenced-by"| SCSS

  %% SCSS / ITCSS layering (vertical chain)
  SCSS -->|"imports"| S01i -->|"aggregates"| S01
  S01i -->|"imports"| S02i -->|"aggregates"| S02
  S02i -->|"imports"| S03i -->|"aggregates"| S03
  S03i -->|"imports"| S04i -->|"aggregates"| S04
  S04i -->|"imports"| S05i -->|"aggregates"| S05
  S05i -->|"imports"| S06i -->|"aggregates"| S06
  S06i -->|"imports"| S99i -->|"aggregates"| S99

  %% Toolchain build transforms
  ParcelDev -->|"compiles"| Sass
  Sass -->|"outputs"| ParcelDev

  %% =========================
  %% Build / Release flow
  %% =========================
  NodeNpm -->|"executes"| Build
  Build -->|"runs"| ParcelBuild
  ParcelBuild -->|"bundles+optimizes"| Dist
  ParcelBuild -->|"compiles"| Sass
  Sass -->|"outputs"| ParcelBuild

  %% CI
  GHA -->|"checks-out"| HTML
  GHA -->|"installs+builds"| ParcelBuild
  GHA -->|"produces"| Dist
  GHA -->|"uses"| ReleaseCfg

  %% Governance hooks
  Git -->|"commit"| Husky
  Husky -->|"runs"| HookPre
  Husky -->|"runs"| HookMsg
  HookMsg -->|"validates"| Commitlint
  HookPre -->|"formats"| Prettier
  HookPre -->|"lints"| Stylelint
  HookPre -->|"hints"| Webhint

  %% Config usage
  Prettier -->|"uses"| PrettierIgnore
  Stylelint -->|"uses"| StylelintIgnore

  %% =========================
  %% Click events (component mapping)
  %% =========================
  click HTML "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/index.html"
  click JS "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/js/index.js"
  click SCSS "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/style/index.scss"

  click S01 "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/style/01-settings/"
  click S01i "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/style/01-settings/_index.scss"
  click S02 "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/style/02-tools/"
  click S02i "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/style/02-tools/_index.scss"
  click S03 "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/style/03-generics/"
  click S03i "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/style/03-generics/_index.scss"
  click S04 "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/style/04-elements/"
  click S04i "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/style/04-elements/_index.scss"
  click S05 "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/style/05-objects/"
  click S05i "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/style/05-objects/_index.scss"
  click S06 "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/style/06-components/"
  click S06i "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/style/06-components/_index.scss"
  click S99 "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/style/99-utilities/"
  click S99i "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/style/99-utilities/_index.scss"

  click IMG "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/img/"
  click FONT "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/font/"

  click Pkg "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/package.json"
  click Lock "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/package-lock.json"
  click Nvm "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.nvmrc"

  click GHA "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.github/workflows/release.yml"
  click ReleaseCfg "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.releaserc.json"

  click Husky "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/.husky/"
  click Commitlint "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/commitlint.config.js"
  click HookMsg "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.husky/commit-msg"
  click HookPre "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.husky/pre-commit"

  click Prettier "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.prettierrc"
  click PrettierIgnore "https://github.com/desenvolvweb/basic-front-boilerplate/tree/master/prettierignore"
  click Stylelint "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.stylelintrc"
  click StylelintIgnore "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.stylelintignore"
  click Webhint "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.hintrc"
  click EditorCfg "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.editorconfig"
  click PostCSS "https://github.com/desenvolvweb/basic-front-boilerplate/blob/master/.postcssrc"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#E8F1FF,stroke:#2B5FB8,stroke-width:1.5px,color:#0B1B3A;
  classDef runtime fill:#D9ECFF,stroke:#1E5AA8,stroke-width:1.5px,color:#0B1B3A;
  classDef tool fill:#FFF1CC,stroke:#C98A00,stroke-width:1.5px,color:#3A2A00;
  classDef cmd fill:#FFE3B3,stroke:#C46B00,stroke-width:1.5px,color:#3A2000;
  classDef build fill:#FFD6B8,stroke:#C14D00,stroke-width:1.5px,color:#3A1500;
  classDef buildInner fill:#FFE3D4,stroke:#C14D00,stroke-width:1px,color:#3A1500;
  classDef entry fill:#DFF7E7,stroke:#1F7A3F,stroke-width:1.5px,color:#0B2A14;
  classDef itcss fill:#CFF3E0,stroke:#1F7A3F,stroke-width:1px,color:#0B2A14;
  classDef itcssIndex fill:#BFEBD5,stroke:#1F7A3F,stroke-width:1px,color:#0B2A14;
  classDef asset fill:#E7FFF3,stroke:#2B9B63,stroke-width:1.5px,color:#0B2A14;
  classDef artifact fill:#F2F2F2,stroke:#666,stroke-width:1.5px,color:#111;
  classDef ci fill:#EFE6FF,stroke:#6B3FA0,stroke-width:1.5px,color:#1D0B2A;
  classDef gov fill:#EBD8FF,stroke:#6B3FA0,stroke-width:1.5px,color:#1D0B2A;
  classDef lint fill:#F6E9FF,stroke:#8A57C2,stroke-width:1px,color:#1D0B2A;
  classDef cfg fill:#F3F7FF,stroke:#355AA6,stroke-width:1px,color:#0B1B3A;
```
