laitszkin/init-project-html

Goal

Produce a project architecture diagram via the apltk CLI. Help users understand the project's software architecture.

Acceptance Criteria

• The diagram covers all four C4 levels: System Context → Container (feature) → Component (submodule) → Code (function row)
• All cross-module and intra-module edges are fully defined
• Every declared component is backed by source code evidence (evidence.sourceFile:sourceLine); unresolved ones are tagged inferred
• Every submodule must declare its functions and variables arrays (mandatory, may not be left empty)

C4 Mapping

This skill's "feature" and "submodule" map to the C4 model as follows:

| C4 Level | Skill Equivalent | Description | When to Use | |----------|-----------------|-------------|-------------| | System Context | Whole system | System boundaries, external actors, and external systems | Step 1 — establish baseline awareness | | Container | Feature | High-level functional boundary (e.g. Login, Payment) | Primary abstraction level | | Component | Submodule | Implementation unit inside a feature (controller, service, repository) | Primary detail level | | Code | Function row | Function-level detail with source file and line evidence | Mandatory — every submodule must declare its functions with evidence.sourceFile:sourceLine |

Mode Detection

At load time, check the project state to select the correct mode:

• design — No resources/project-architecture/atlas/ directory exists. Run full C4 initialization. Use --evidence observed for source-confirmed components.

• record — Atlas directory exists but is near-empty (< 2 features). Run quick feature-by-feature recording using apltk architecture scan to discover candidates. Use --evidence inferred for structurally inferred components.

• update — Atlas has substantive content and source code has changed. Delegate to update-project-html skill for drift measurement and incremental update.

• review — An architecture_diff/ overlay directory exists. Run diff comparison workflow. If no diff found, fallback to update mode.

• guard — If you are explicitly instructed to run design/init mode but the atlas directory already exists and is non-empty, pause and ask the user whether to: (a) overwrite the existing atlas, (b) switch to update mode, or (c) abort.

Workflow

Applicable modes: design (full initialization), record (quick recording)

1. Survey the project with apltk codegraph survey

Before diving into the code, establish a high-level understanding:

• Which external actors interact with the system (users, third-party services, other systems)
• What high-level capabilities the system provides

Then read sample-demo/ to understand the expected output format and abstraction level.

Next, run apltk codegraph survey to get a structured survey report:

• List of all files in the project directory with function counts
• Entry points (public functions called from external files)
• Suggested submodule groupings and cross-boundary edges
• Supports --json output for programmatic consumption by the LLM

Based on the survey report, decide how to partition features (C4 Container level):

• Group closely interconnected function clusters into the same feature's submodules
• Identify feature boundaries and cross-feature call relationships
• Record the directory path and entry points for each feature

2. Write the atlas with apltk architecture apply

Generate the atlas incrementally by C4 level: Consult references/architecture.md for CLI flag details when needed (parameter reference, mutation series).

1. System Context: Define external actors, system boundaries, and cross-system edges
2. Container level: Define features and their inter-feature edges
3. Component level: Define submodules with their internal elements (function, variable, dataflow, error)
4. Code level: Declare functions and variables for every submodule, attaching evidence (source file and line number via --evidence observed:path/file.ts:42)

Use apltk architecture apply <proposal.yaml> for batch atlas writes (replaces manual per-mutation CLI calls). Transform the codebase knowledge gathered in the previous step into a clear architecture diagram. After completion, verify the atlas format is valid and renders correctly.

3. Self-review

Confirm the following before finishing:

• [ ] All four C4 levels are populated (Context → Container → Component → Code)
• [ ] Every submodule has at least one function declared with source evidence
• [ ] All cross-feature and intra-feature edges are defined
• [ ] Evidence level is correctly set (observed for source-confirmed, inferred otherwise)
• [ ] Atlas passes apltk architecture validate

Evidence Traceability

Every component declared via the CLI must carry source evidence:

• Feature → corresponding directory path or entry point file
• Submodule → list of files implementing the module
• Function row → source file and line number (evidence.sourceFile + evidence.sourceLine)
• Edge → code location triggering the call relationship

If time or context constraints prevent full traceability, record the scanned scope and known gaps in meta.summary.

References

• references/architecture.md — Full parameter reference for the apltk architecture tool (consult when CLI flag details are needed).
• references/TEMPLATE_SPEC.md — Atlas field reference, enum values, and CLI shape cheat sheet.
• references/definition.md — Detailed definitions of feature and submodule.
• assets/architecture-page.template.html — HTML template.
• references/architecture.css — Style template.
• sample-demo/ — Complete example output for understanding the final atlas shape and C4 level mapping.