esplotter/architecture

<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. Edit files under IA/ and run `bash IA/sync-ai-files.sh` to regenerate. -->

Skill: Architecture

This skill defines how to evaluate and apply changes while preserving ESPlotter architecture. It is the default baseline for architecture-focused reviews and refactors.

Primary source:

• docs/architecture/architecture.md

Scope

Use when

• Reviewing or changing boundaries between main, preload, renderer, and shared.
• Adding new features in src/app/main/<feature>/.
• Reviewing IPC flow, use-case entry points, repository/service placement, or module responsibilities.
• Validating that business logic is not leaking to preload/renderer.

Do NOT use when

• The task is only coding style/type quality without boundary impact -> use code-standards.
• The task is only test strategy/suite selection -> use tests and routed test skills.

Architectural baseline (non-negotiable)

• Main process follows hexagonal layering:
  • domain: business rules, no Electron/external API imports.
  • application: use cases orchestrating domain and ports.
  • infrastructure: adapters for IPC, persistence, filesystem, observers.
• Use cases are the only backend entry points for business behavior.
• main.ts only handles app lifecycle and feature registration.
• Features must be lazily loaded via dynamic imports (mandatory rule).
• Business logic must not live in preload or renderer.

Layer-specific rules

Main (src/app/main)

• Keep domain and application framework-agnostic.
• Do not import electron, fs, fetch, or similar in use cases.
• Put persistence/external integrations behind repositories/services in infrastructure.

Preload (src/app/preload)

• Only expose thin, typed bridge APIs.
• No business logic, no persistence logic, no stateful behavior.
• No direct imports from @main.
• Group APIs by namespace in window and delegate through shared IPC contracts.

Renderer (src/app/renderer)

• Keep renderer as presentation/UI orchestration only.
• Domain data must come through preload-exposed APIs.
• No imports from @main or @preload.
• Global UI state is allowed; domain/persistence state remains in main.

Shared (src/app/shared)

• Keep shared code reusable and generic.
• Avoid feature-specific behavior in shared modules.

Review checklist

For each architecture review, verify:

1. Boundary integrity
   • Responsibilities are in the correct layer.
   • No forbidden imports crossing boundaries.
2. Entry-point integrity
   • Main business behavior is driven through use cases.
   • Preload stays thin and delegating.
3. Dependency direction
   • Domain/application do not depend on infrastructure/Electron APIs.
4. Extensibility
   • The design supports expected evolution without broad rewrites.
5. Consistency
   • New code matches established patterns in neighboring modules.

Anti-patterns (blocker)

• Business rules implemented in preload or renderer.
• Use cases importing infrastructure or runtime APIs directly.
• IPC handlers containing domain logic instead of delegating to use cases.
• Eager feature loading in main.ts when lazy dynamic loading is possible.
• Shared modules polluted with feature-specific code.
• Tight coupling that bypasses ports/adapters and prevents isolated testing.

Definition of done

• Architecture risks are identified with evidence and severity.
• Violations are mapped to concrete minimal fixes.
• Recommendations preserve existing project conventions and avoid over-refactor.

Output contract

Return a structured YAML report including:

• status: ok | needs_clarification | error
• summary: one-paragraph architecture assessment
• scope: files/modules and assumptions reviewed
• findings: list of findings with title, severity, evidence, rule, fix
• verdict: ready | ready_with_changes | not_ready
• next_actions: ordered, minimal action plan
• warnings: assumptions, risks, or unresolved questions