App documentation

[Sistema2D]

Language / Idioma:
PT-BR | EN-US

---

PT-BR - Definir estrutura de governança para documentação dos módulos da aplicação

Contexto

Atualmente, o FrameCode VibeWork não possui uma pasta nem um fluxo formalmente definidos para a documentação das páginas, telas e módulos da aplicação em desenvolvimento.

Embora esse tipo de documentação faça parte do escopo de governança do FCVW, ainda não existe uma estrutura padronizada para orientar onde esses documentos devem ser armazenados, qual conteúdo mínimo devem conter e como devem representar a lógica de funcionamento dos módulos.

Problema

A ausência de uma estrutura de documentação para os módulos da aplicação pode gerar inconsistências entre projetos e dificultar a manutenção evolutiva do sistema.

Sem um padrão mínimo, diferentes agentes ou desenvolvedores podem documentar módulos de formas diferentes, por exemplo:

• registrar apenas descrições textuais;
• omitir fluxos de funcionamento;
• não documentar dependências entre páginas, componentes e arquivos;
• não registrar regras de negócio associadas ao módulo;
• misturar documentação do framework com documentação da aplicação;
• armazenar documentos em locais diferentes da estrutura do projeto.

Isso reduz a rastreabilidade, dificulta auditorias técnicas e enfraquece a governança da aplicação em desenvolvimento.

Proposta

Criar uma estrutura oficial para documentação das páginas e módulos da aplicação desenvolvida com apoio do FCVW.

A regra deve definir que:

1. A documentação da aplicação deve ficar em uma pasta própria na raiz do projeto.
2. A pasta deve ser separada da pasta interna do framework, ainda que siga regras definidas pelo FCVW.
3. Cada módulo, tela ou página relevante deve possuir um documento próprio.
4. O framework deve fornecer templates com escopo mínimo obrigatório.
5. Cada documento deve incluir uma referência visual da lógica de funcionamento do módulo.
6. O uso de Mermaid deve ser recomendado para representar fluxos, dependências e interações.

Estrutura sugerida

/
├── FCVW/
├── docs/
│   ├── README.md
│   ├── modules/
│   │   ├── TEMPLATE_MODULE.md
│   │   ├── home.md
│   │   ├── dashboard.md
│   │   └── ...
│   └── flows/
│       ├── TEMPLATE_FLOW.md
│       └── ...

Escopo mínimo recomendado para cada módulo

Cada documento de módulo deve conter, no mínimo:

• nome do módulo;
• objetivo do módulo;
• páginas, arquivos ou componentes relacionados;
• entradas esperadas;
• saídas produzidas;
• regras de negócio aplicáveis;
• dependências internas;
• dependências externas;
• eventos ou ações do usuário;
• estados possíveis;
• critérios de validação;
• riscos conhecidos;
• fluxograma ou diagrama Mermaid;
• histórico de alterações relevantes.

Exemplo de diagrama Mermaid

flowchart TD
    A[Usuário acessa o módulo] --> B[Interface carrega dados iniciais]
    B --> C{Dados disponíveis?}
    C -- Sim --> D[Renderizar conteúdo]
    C -- Não --> E[Exibir estado vazio]
    D --> F[Usuário executa ação]
    F --> G[Validar entrada]
    G --> H{Entrada válida?}
    H -- Sim --> I[Atualizar estado e persistir dados]
    H -- Não --> J[Exibir mensagem de erro]

Loading

Diretriz recomendada

A documentação dos módulos deve ser tratada como parte da governança do projeto, mas não deve ser armazenada dentro da pasta interna do framework.

A pasta FCVW/ deve conter as regras, templates e diretrizes de governança.

A pasta docs/, localizada na raiz do projeto, deve conter a documentação específica da aplicação em desenvolvimento.

Dessa forma, o framework define o padrão, mas a documentação gerada pertence ao projeto.

Arquivos provavelmente afetados

• FCVW/PLANNING.md
• FCVW/WORKFLOW.md
• FCVW/AUDIT.md
• FCVW/governance/TEMPLATE_PLAN.md
• AGENTS.md
• novo template para documentação de módulos
• nova pasta docs/ na raiz do projeto
• novo arquivo docs/README.md
• novo arquivo docs/modules/TEMPLATE_MODULE.md
• novo arquivo docs/flows/TEMPLATE_FLOW.md

Critérios de aceitação

• O framework define onde a documentação da aplicação deve ser armazenada.
• A documentação da aplicação é criada em pasta própria na raiz do projeto.
• A pasta de documentação da aplicação não é criada dentro de FCVW/.
• Existe um template mínimo para documentação de módulos.
• Existe orientação para documentar páginas, telas e componentes relevantes.
• Existe recomendação explícita para uso de fluxogramas ou diagramas Mermaid.
• O template inclui campos para objetivo, arquivos relacionados, regras de negócio, dependências, estados, validações e riscos.
• AGENTS.md orienta a IA a consultar e atualizar a documentação dos módulos quando alterar a aplicação.
• AUDIT.md verifica se alterações relevantes em módulos também atualizaram a documentação correspondente.

---

EN-US - Define a governance structure for application module documentation

Context

FrameCode VibeWork currently does not have a formally defined folder or workflow for documenting the pages, screens, and modules of the application under development.

Although this type of documentation belongs to the FCVW governance scope, there is still no standardized structure defining where these documents should be stored, what minimum content they should include, and how they should represent each module’s operating logic.

Problem

The lack of a documentation structure for application modules may create inconsistencies across projects and make system maintenance more difficult.

Without a minimum standard, different agents or developers may document modules in different ways, for example:

• recording only textual descriptions;
• omitting operating flows;
• failing to document dependencies between pages, components, and files;
• failing to register business rules associated with the module;
• mixing framework documentation with application documentation;
• storing documents in different locations within the project structure.

This reduces traceability, makes technical audits harder, and weakens governance over the application under development.

Proposal

Create an official structure for documenting the pages and modules of the application developed with FCVW support.

The rule should define that:

1. Application documentation must be placed in its own folder at the project root.
2. This folder must be separate from the internal framework folder, even though it follows rules defined by FCVW.
3. Each relevant module, screen, or page should have its own document.
4. The framework should provide templates with a mandatory minimum scope.
5. Each document should include a visual reference for the module’s operating logic.
6. Mermaid should be recommended for representing flows, dependencies, and interactions.

Suggested structure

/
├── FCVW/
├── docs/
│   ├── README.md
│   ├── modules/
│   │   ├── TEMPLATE_MODULE.md
│   │   ├── home.md
│   │   ├── dashboard.md
│   │   └── ...
│   └── flows/
│       ├── TEMPLATE_FLOW.md
│       └── ...

Recommended minimum scope for each module

Each module document should include at least:

• module name;
• module purpose;
• related pages, files, or components;
• expected inputs;
• produced outputs;
• applicable business rules;
• internal dependencies;
• external dependencies;
• user events or actions;
• possible states;
• validation criteria;
• known risks;
• flowchart or Mermaid diagram;
• relevant change history.

Mermaid diagram example

flowchart TD
    A[User accesses the module] --> B[Interface loads initial data]
    B --> C{Data available?}
    C -- Yes --> D[Render content]
    C -- No --> E[Show empty state]
    D --> F[User performs action]
    F --> G[Validate input]
    G --> H{Valid input?}
    H -- Yes --> I[Update state and persist data]
    H -- No --> J[Show error message]

Loading

Recommended guideline

Module documentation should be treated as part of project governance, but it should not be stored inside the internal framework folder.

The FCVW/ folder should contain the governance rules, templates, and guidelines.

The docs/ folder, located at the project root, should contain the documentation specific to the application under development.

This way, the framework defines the standard, while the generated documentation belongs to the project.

Likely affected files

• FCVW/PLANNING.md
• FCVW/WORKFLOW.md
• FCVW/AUDIT.md
• FCVW/governance/TEMPLATE_PLAN.md
• AGENTS.md
• new module documentation template
• new root-level docs/ folder
• new docs/README.md
• new docs/modules/TEMPLATE_MODULE.md
• new docs/flows/TEMPLATE_FLOW.md

Acceptance criteria

• The framework defines where application documentation should be stored.
• Application documentation is created in its own folder at the project root.
• The application documentation folder is not created inside FCVW/.
• A minimum template for module documentation exists.
• There is guidance for documenting relevant pages, screens, and components.
• There is an explicit recommendation to use flowcharts or Mermaid diagrams.
• The template includes fields for purpose, related files, business rules, dependencies, states, validations, and risks.
• AGENTS.md instructs the AI to consult and update module documentation when changing the application.
• AUDIT.md verifies whether relevant module changes also updated the corresponding documentation.