t1k:cocos:base:clean-architecture

Field	Value
Module	`base`
Version	`3.3.2`
Effort	`medium`
Tools	—

Keywords: 4-layer architecture, application layer, clean architecture, composition root, domain layer, eslint-plugin-import, hexagonal architecture, infrastructure layer, module contract, no-restricted-paths, ports and adapters, presentation layer, signalbus, vitest

How to invoke

/t1k:cocos:base:clean-architecture
[refactor target | feature to design]

Cocos Clean Architecture (4-Layer)

Cocos specialization of theonekit-core’s t1k-game-arch skill: 4-layer Clean Architecture (Domain / Application / Presentation / Infrastructure) with a manual composition root, signalBus, eslint-plugin-import no-restricted-paths, and Vitest. This skill does NOT introduce new universal principles — those live in t1k-game-arch (theonekit-core). If a rule applies to Unity too, it belongs there, not here.

Not the same thing as t1k-cocos-base-architecture-patterns. That skill grades a codebase’s Service/Component/Controller structure against its own docs/system-design.md doctrine (pooling, FSM, SignalBus, component-split triggers). This skill is a different, opt-in architectural style for features whose rules/formulas/state transitions outlive one deliverable — pick one style per module, not both. If the project already has a docs/system-design.md doctrine, specialize this layering to fit it rather than big-banging a rewrite (t1k-game-arch’s own “starter pattern, adapt as needed” guidance applies here too).

When to use

A feature’s Domain rules (damage formulas, quest state machines, economy math) need to be 100% unit-testable without booting the engine.
Refactoring a god-cc.Component into layered, testable code.
Scaffolding a new feature module from a Game Design Document.
Not for a short-lived playable-ad module — see t1k-cocos-playable-modularize for that root’s own module boundary instead.

Decision tree

Intent	Load
Composition root, signalBus, eslint zones, Vitest, module-directory contract	`references/clean-architecture.md`
Scaffold a new 4-layer feature module (directory tree + `index.ts` stub)	`references/clean-architecture-scaffold.md`
The 4 layers, dependency rule, port/event/command rules, testing pyramid	Not here — theonekit-core `t1k-game-arch`
`module-contract.md` template + worked examples	Not here — theonekit-core `t1k-game-arch` `module-contracts.md`
Grading a `Service`/`Component`/`Controller` codebase against `docs/system-design.md`	Not here — `t1k-cocos-base-architecture-patterns`

theonekit-core t1k-game-arch — engine-agnostic doctrine this skill specializes
theonekit-unity t1k-unity-base-game-patterns § Clean Architecture (4-Layer) — parallel Unity specialization
t1k-cocos-base-architecture-patterns — the Service/Component/Controller doctrine and its audit (a different, non-exclusive style)
t1k-cocos-base-system-design — owns docs/system-design.md and verify-manifest.cjs
t1k-cocos-playable-signalbus — signalBus mechanics in the playable-ad context specifically