Architecture And Design

Architecture and Design — Base Engineering Skill

Framework-neutral architecture standards, design principles, and structure patterns for web applications in TypeScript. The principles hold for React, Angular, Vue, and any component-based framework. Code examples use React/TSX for one concrete syntax; each principle has an equivalent in an Angular template or a Vue SFC.

Builds on. core-typescript (language syntax). On a shared topic this skill decides the design and core-typescript decides the syntax. react, angular, or vue gives the framework form and accessibility the UI lens. Load a sibling only when the task turns on its layer; if it is not loaded, apply that layer from general knowledge and do not block.

This SKILL.md is self-sufficient: the Ruleset below is the complete, enforceable list. Each references/<topic>.md holds that group's reasoning and ❌ / ✅ code, and references/worked-example.md a full review pass; open them for depth when your runtime allows.

How to Use This Skill

Pick the mode that matches the task. Do the steps in order.

Output Format

Write one finding per line:

<severity> · <topic> · <file>:<line> — <what is wrong>. <the fix as an action>.

• <severity> is must-fix (breaks a rule in this skill) or consider (safe, but a rule prefers another form).
• <topic> is a Ruleset topic slug (state-and-data, type-safety, security, …).

Rules for Every Mode

• Name the Ruleset topic when you enforce a rule.
• State the reason, not only the rule. "This re-renders the whole tree" beats "move state down".
• Name the rule and the change; do not rewrite the author's code in silence.
• A principle serves the code. When two principles conflict, pick the one that makes the code simpler to read and change, and say why.
• When the task is a decision, not a diff, weigh the options against solid, clean-architecture, structure, state-and-data, and micro-frontends, and record the choice as an ADR in the repo using assets/adr-template.md (context, options, decision, consequences).

Ruleset

solid → references/solid.md

• SRP: rendering is separated from data fetching, state transitions, and domain math (into components, hooks, services, pure functions).
• OCP: component variability comes from children, slots, or render props — never a boolean flag per variant.
• LSP: a custom primitive or a mock honors the full interface its consumers expect.
• ISP: a component receives the exact props it reads, not a whole domain entity.
• DIP: business logic and UI depend on an injected interface, token, or context — not a concrete client, SDK, or localStorage.

clean-code → references/clean-code.md

• Booleans named is / has / should / can; functions named with a verb; one term per concept, no unclear abbreviations.
• Functions short enough to read without scrolling; the parameter-list shape is core-typescript, functions.
• No boolean flag parameter that switches behavior — two functions instead.
• Comments say why, not what; no dead code (commented blocks, unused exports, unreachable branches).
• No mutation of a parameter, prop, or state in place — a new value is built and returned.
• Every error is handled or rethrown — never an empty catch.

expressive-logic → references/expressive-logic.md

• No x ? true : false, no if (c) return true; else return false, no comparison against a boolean literal.
• Guard clauses over nested conditionals; every condition stated in the positive.
• A long boolean chain is given a name (a variable or a predicate function).
• ?. / ?? over a manual && null chain (when ?? beats || is core-typescript, nullability).
• Magic numbers and strings have named constants.
• An if/else if ladder on one value is a typed lookup or an exhaustive switch with an assertNever default.

type-safety → references/type-safety.md

• External input enters as unknown and is narrowed at the boundary; the any and cast syntax rules are core-typescript, unsafe-types.
• Mutually exclusive states are a discriminated union, not an object of optional fields.
• Illegal values are unrepresentable: readonly, as const, branded id types.
• Network data is parsed against a schema at the adapter, then mapped to the domain model.
• API types are generated from the contract (OpenAPI, GraphQL codegen, tRPC), not hand-written.
• Environment and runtime config are validated against a schema at startup.

clean-architecture → references/clean-architecture.md

• The domain core has zero framework, DOM, or network imports.
• Dependencies point inward: UI → use cases → domain; infrastructure implements the domain's interfaces (dependency inverted).

structure → references/structure.md

• Code is organized by business feature, not by technical role (no components/ / services/ / utils/ dumping grounds).
• features import shared; shared never imports features.
• A feature never imports another feature's internal files — only its index.ts, shared state, or routing.
• The boundary is enforced by a linter (eslint-plugin-boundaries, Nx module boundaries).

patterns → references/patterns.md

• A third-party library, SDK, or raw API response is hidden behind an adapter / repository that returns a domain model.
• Async state is a discriminated union with a status discriminant — not loose isLoading / isError / hasData booleans.

state-and-data → references/state-and-data.md

• State is colocated in the component that uses it; lifted only when a second component needs it.
• A value that can be computed from props or other state is derived, not stored.
• A server collection held in a client store is normalized — each entity once, keyed by id; data in a query cache stays as fetched.
• Each state kind sits in its tier: server-cache library / URL params / a small store or context / the component.
• Context holds only low-frequency values; a fast-changing value goes in a store with selectors, not a wide context.
• Server data goes through a cache library keyed by its inputs — not fetched in an effect into local state.
• Server data is fetched at the point of use, not prop-drilled from a far ancestor.
• Independent requests load in parallel, not as a parent → child waterfall.
• A mutation updates the cache from its response; an optimistic update has a rollback path.
• An explicit stale time and retry policy per query type.

frontend-practices → references/frontend-practices.md

• Filters, maps, and chains are computed before the return, out of the template.
• Every async state is modeled: loading, empty, error, success.
• List keys are stable ids, never the array index for a list that can reorder.
• A derived value or an event handler over a lifecycle side effect; a side effect that remains has one concern and a cleanup.
• Each independent region has its own error boundary and fallback, not only the app root.
• A stale async result is cancelled or ignored (AbortController or an ignore flag).
• A caught error is sent to a tracker with the source map, the release tag, and session context.
• No console.log ships; logging goes through one structured logger.
• A semantic element over a div with a handler; every input and icon-only control labelled. Full lens: accessibility.

security → references/security.md

• No HTML is built from untrusted input; what must render as HTML is sanitized (DOMPurify) first.
• dangerouslySetInnerHTML / [innerHTML] / v-html and every bypassSecurityTrust* are avoided; each remaining use is reviewed.
• No secrets in the bundle — a third-party key lives on a server.
• rel="noopener noreferrer" on every target="_blank" link.
• A redirect URL from a query param is checked against an allowlist; a javascript: or data: URL from user data is rejected.
• Token storage is chosen on purpose and the trade-off is written down.
• CSP in enforcing mode, nonce-based for scripts; Trusted Types where the browser supports it.
• With cookie auth, an anti-CSRF token on every state-changing request, and SameSite set.
• A third-party <iframe> has a sandbox with only the capabilities it needs.
• A new dependency is reviewed before adding it (maintenance, transitive weight, provenance).

testing → references/testing.md

• The suite is weighted toward integration: a static-analysis base, unit tests for pure logic, a thick layer of component-plus-collaborator tests with the network mocked at the edge, a thin top of end-to-end tests for critical paths.
• Domain and use cases: fast unit tests on plain functions, no DOM or network.
• Components: queried by role and label, asserted on what the user sees; a data-testid only when no accessible name fits.
• Coverage is enforced on the lines a change touches, not a global percentage.
• Every bug fix ships with a test that fails before the fix.
• The API boundary is contract-tested, or types are generated from the contract and the payload validated.
• A flaky test is quarantined on the first flake and fixed within the sprint.
• A snapshot is used only for small, stable output.
• Each test also passes the test-quality Ruleset — asserts on behavior not implementation, has a meaningful assertion, is deterministic and order-independent. This group decides the suite shape; test-quality judges the individual test.

ddd → references/ddd.md

• One ubiquitous name per concept across code, tests, UI, and API (Cart everywhere, not Basket / Order).
• Entities and value objects live in the feature's model/, free of framework and network code.
• A value object is immutable — a new instance to change it.
• An aggregate's inner parts are reached only through its root.
• A domain event is named in the past tense and treated as a fact, not a command.
• One model per bounded context; translate at the edge.

micro-frontends → references/micro-frontends.md

• The default is a modular monolith; a split happens only when an independent per-team deploy is the actual bottleneck.
• The shell and each remote share a versioned contract: a mount function, props in, events out.
• The framework and the design system are shared as pinned singletons.
• A remote that fails to load or throws does not blank the shell.
• Routing and auth stay in the shell; identity passes down.

forms → references/forms.md

• Draft state is local to the form or a form library — never lifted into global state.
• One validation schema, next to the domain model, reused on client and server.
• isValid / isDirty / per-field errors are derived from form state, not stored.
• Uncontrolled inputs with a form library for a large form; a field component's controlled / uncontrolled contract is component-api-design.
• A server validation error is mapped back onto its field.
• Submit is disabled while a submit is in flight; entered values survive a failed submit.

Limits

This skill covers frontend architecture and design. It does not cover:

• Backend, database, or infrastructure design.
• Distributed systems — microservices, event-driven backends, sagas. ddd covers tactical patterns inside one app; micro-frontends the frontend split only.
• Styling, tokens, and CSS architecture — styling-and-design-tokens.
• Accessibility beyond "a semantic element and a label" — accessibility.
• Performance budgets, Core Web Vitals, and bundle analysis — web-performance.
• A reusable component's public API (component-api-design) and internationalization (i18n-and-localization).
• CI configuration, dependency bots, release tooling, and monorepo setup.
• Framework-specific rules (hooks, memoization, change detection, reactivity) — react / angular / vue.

This skill states principles. It is not a substitute for reading the code and understanding the domain.

References

This skill composes with:

• core-typescript — the language base. On a shared topic this skill decides the design and core-typescript decides the syntax.
• react / angular / vue — the framework form of these rules. Apply the matching one in a React, Angular, or Vue codebase; it wins on a direct conflict.
• accessibility — the review lens for UI: ARIA, keyboard and focus, live regions, a11y testing.
• test-quality — this skill's testing group sets the suite shape; test-quality judges each individual test.