Spec — Project Layout

Facet *ode*do Koder Design.

Cobre *ayout intra-módulo*(dentro de um Sector). Layout intermódulo (<domain>/<area>/<sector>/) é RFC006.

Princípio cross-cutting

Cada linguagem tem o seu *diom estabelecido*(Go cmd/+internal/, Rust src/+tests/, Dart lib/+test/, etc.). A Koder respeita o idiom — não inventa layout próprio que confunde tooling oficial.

Onde *niformizar*entre todas:

• README.kmd na raiz do módulo (per readmes/products.kmd)
• koder.toml na raiz (per koder-toml/format.kmd)
• .editorconfig na raiz (per code/indentation.kmd)
• LICENSE na raiz
• docs/ pra documentação intra-módulo (KMD/MD)
• backlog/ pra tickets do módulo (per policies/backlog.kmd)
• dist/, build/, target/, out/ *empre*gitignored

Tabela canônica per linguagem

Go

<module>/
├── README.kmd
├── koder.toml
├── .editorconfig
├── LICENSE
├── go.mod
├── go.sum
├── cmd/
│   └── <bin-name>/main.go    ← um dir por binário
├── internal/                 ← código não-exportável
│   ├── <pkg>/
│   └── ...
├── pkg/                      ← código exportável (se library)
├── api/                      ← spec proto/openapi (se relevante)
├── testdata/                 ← fixtures pra _test.go
├── docs/
├── backlog/
├── examples/                 ← se library
├── scripts/                  ← bash auxiliares
└── dist/                     ← gitignored: build outputs

• Tests: arquivo _test.go *exttosource*(idiom Go)
• Fixtures: testdata/ (Go ignora por convenção)

Rust

<module>/
├── README.kmd
├── koder.toml
├── .editorconfig
├── LICENSE
├── Cargo.toml
├── Cargo.lock              ← commit em binary; gitignore em library
├── src/
│   ├── lib.rs              ← biblioteca
│   ├── main.rs             ← binário
│   └── bin/<name>.rs       ← múltiplos binários
├── tests/                  ← integration tests (cada arquivo = crate)
├── benches/                ← benchmarks
├── examples/               ← idiom Cargo
├── docs/
├── backlog/
└── target/                 ← gitignored

• Unit tests: #[cfg(test)] mod tests no mesmo arquivo (idiom Rust)
• Integration: tests/

Dart / Flutter

<module>/
├── README.kmd
├── koder.toml
├── .editorconfig
├── LICENSE
├── pubspec.yaml
├── pubspec.lock            ← commit em app; gitignore em library
├── lib/
│   ├── <module>.dart       ← entry público
│   └── src/                ← implementação (não exportada)
├── test/
├── integration_test/       ← Flutter integration tests
├── example/                ← se library
├── android/, ios/, ...     ← se Flutter app
├── assets/                 ← se Flutter app
├── docs/
├── backlog/
└── build/                  ← gitignored

Python

<module>/
├── README.kmd
├── koder.toml
├── .editorconfig
├── LICENSE
├── pyproject.toml          ← PEP 518; preferred sobre setup.py
├── <package_name>/         ← snake_case; src layout opcional (recomendado pra evitar import shadowing)
│   ├── __init__.py
│   └── ...
├── tests/                  ← preferred sobre next-to-source
│   ├── conftest.py
│   └── test_*.py
├── docs/
├── examples/
├── backlog/
└── dist/, build/, .venv/   ← gitignored

• src layout (src/<package_name>/) recomendado pra projetos

  publicados — evita import shadowing.

Koda

<module>/
├── README.kmd
├── koder.toml
├── .editorconfig
├── LICENSE
├── lib/                    ← código fonte
│   ├── <module>.kd
│   └── ...
├── test/
│   └── *_test.kd
├── docs/
├── examples/
├── backlog/
└── out/                    ← gitignored

JS/TS

<module>/
├── README.kmd
├── koder.toml
├── .editorconfig
├── LICENSE
├── package.json
├── package-lock.json       ← commit (npm) ou pnpm-lock.yaml (pnpm)
├── tsconfig.json           ← se TS
├── src/                    ← preferred
│   ├── index.ts
│   └── ...
├── test/                   ← Jest/Vitest setup
│   └── *.test.ts
├── docs/
├── examples/
├── public/                 ← se web app
├── backlog/
└── dist/, node_modules/    ← gitignored

Shell scripts (módulo standalone)

<module>/
├── README.kmd
├── koder.toml
├── LICENSE
├── bin/                    ← scripts executáveis (chmod +x)
│   └── <script>
├── lib/                    ← funções source-able
│   └── <lib>.sh
├── test/                   ← bats-core ou similar
├── docs/
└── backlog/

R1 — Tests location

*rincípio* seguir idiom da linguagem. A Koder não força uniformidade contra o tooling oficial.

R2 — Fixtures / testdata

R3 — Resources / assets

• *tatic assets*(imagens, fonts): assets/ (Flutter), static/

  (Go web), public/ (JS web)

• *emplates* templates/ (PythonGo) ou `views` (Rails-like)
• *igrations DB* migrations/ na raiz do módulo

R4 — Build artifacts (sempre gitignored)

.gitignore template canônico em meta/docs/stack/specs/code/gitignore.template.

R5 — Generated code

Quando código é gerado por tooling (protoc, openapi-generator, codegen Koder):

• *arker comment*no header: // Code generated by <tool>. DO NOT EDIT.
• *iretório*gen/ ou per-tool (protoc/)
• *itignore*quando reproduzível trivialmente (build step rápido)
• *ommit*quando custoso/lento ou quando o gerador não é parte

  do build padrão

R6 — Config files

• *roject config* koder.toml na raiz (sempre)
• *anguage config* .golangci.yml, pyproject.toml,

  analysis_options.yaml, tsconfig.json — na raiz

• *ditor* .editorconfig na raiz (sempre)
• *nv* .env.example na raiz; .env gitignored
• *I* .gitea/workflows/ (Gitea Actions)

R7 — Docs intra-módulo

• README.kmd na raiz (overview, install, usage curto)
• docs/ pra docs maiores (docs/getting-started.kmd,

  docs/api.kmd, docs/architecture.kmd)

• ADRs em docs/decisions/NNNN-<title>.kmd (per

  policies/content-location.kmd)

• RFCs intramódulo em `docsrfcsscopeRFCNNtitle.kmd`

R8 — Examples

Quando o módulo é library, examples/ com 1+ exemplos completos runnable. Cada exemplo standalone (não compartilha state com outros).

Audit deterministic

project-layout-audit.sh:

1. README.kmd, koder.toml, .editorconfig, LICENSE na raiz
2. Diretório de build na lista de gitignored
3. Generated code com marker comment
4. Tests em location idiomática (warning se inconsistente)

Cross-link

• RFC006 (sector layout intermódulo)
• code/imports.kmd (import paths refletem layout)
• readmes/products.kmd (README format)
• koder-toml/format.kmd (config canônica)
• policies/backlog.kmd (backlog/ directory)
• policies/content-location.kmd (where to put doc types)