expo-architecture

@architecture-rules.md @rules/project-structure.md @rules/routing-and-navigation.md @rules/data-state-and-boundaries.md @rules/native-platform-and-security.md @rules/testing-and-validation.md @references/official/expo-react-native-2026-08-03.md

Expo Architecture

Create and enforce scalable React Native + Expo + TypeScript architecture for Android and iOS while separating official framework behavior from Hypercore conventions.

<output_language>

Default user-facing deliverables, reports, plans, handoff notes, and validation notes to Korean. Preserve code identifiers, commands, paths, schema keys, package names, API names, and source excerpts in their required language.

</output_language>

• Bootstrap or refactor Expo applications around Expo Router, strict TypeScript, feature boundaries, and explicit native-platform seams.
• Keep route files thin and organize growing product code by domain/feature rather than by one global technical bucket.
• Protect secrets, permissions, native configuration, storage, and Android/iOS divergence with explicit gates.
• Validate architecture against the installed Expo SDK and project evidence before applying current official guidance.

<routing_rule>

Use this skill for architecture setup, implementation, review, or remediation in Expo-managed or Expo prebuild projects targeting Android and iOS.

Do not use it for bare React Native without Expo, generic web React, a single visual component with no architecture impact, deployment-only work, or documentation-only summaries. For brownfield apps, preserve working project conventions unless the user requests migration or a safety/correctness issue requires change.

</routing_rule>

<instruction_contract>

Field	Contract
Intent	Produce a scalable, testable Expo architecture whose route, feature, data, native, and platform boundaries remain understandable as the app grows.
Trigger	Expo/React Native/TypeScript work involving app setup, folder structure, Expo Router, state/data flow, native configuration, platform divergence, testing, or architecture review.
Scope	Touched app configuration, TypeScript source, route tree, feature/shared modules, tests, and architecture validation notes; broad native regeneration and dependency replacement require explicit scope.
Authority	User and project instructions outrank this skill. Installed package/config evidence controls project behavior. Official Expo/React Native docs control API facts; Hypercore conventions are recommendations unless adopted by the project.
Evidence	Inspect package.json, app config, router entry, TypeScript/Metro/Babel config, native directories, existing source/tests, and lockfile first. Use dated official references when version drift matters.
Tools	Use capability-based inspect/read/search/edit/execute. Validate commands and paths. Gate network installs, credentials, EAS operations, native clean regeneration, signing, publication, deployment, and production effects.
Loop	Use a bounded verify-repair loop: run relevant checks, repair only observed failures, and stop after two repair passes. Keep changes only when critical type, route, native-config, and safety guards pass.
Output	A project-local architecture implementation or review, plus a concise Korean report of decisions, changed files, checks, source/version caveats, and residual risks.
Verification	Run project-defined format/lint/type/test checks plus Expo diagnostics and platform checks relevant to touched surfaces; inspect resolved config and route behavior when changed.
Stop condition	Finish when project mode and SDK are identified, applicable critical gates pass, changes are verified, and residual risk is recorded; block on missing authority, unsafe native effects, unresolved package incompatibility, or unavailable required verification.

</instruction_contract>

<activation_examples>

Positive:

• "Set up an iOS/Android app structure with React Native + Expo + TypeScript that is scalable."
• "Refactor the routes, features, API, and state boundaries of the Expo Router app."
• "Audit this Expo app for scalable architecture and platform-boundary violations."
• "Set up the Expo project structure considering the EAS environment and iOS/Android configuration as well."

Negative:

• "Design the native module architecture of a Bare React Native CLI app."
• "Only fix the CSS of this React web component."
• "Just summarize the Expo documentation."

Boundary:

• "Change just one piece of text on the Expo login screen." Apply only a quick boundary check; do not force architecture churn.
• "Deploy the Expo app to the store." Use this skill only for architecture/config review; deployment authorization and execution belong to the deployment workflow.

</activation_examples>

<project_validation>

Before enforcement, identify:

1. Expo SDK, React Native, Expo Router, TypeScript, package manager, and workspace mode from local files.
2. Managed/CNG, committed ios/ or android/, development build, or Expo Go constraints.
3. Existing route root (src/app or app), aliases, generated files, tests, and project commands.
4. Whether requested changes need package installation, prebuild, EAS, credentials, signing, or store-side effects.

If the target is not Expo and the user did not request creating an Expo app, stop routing through this skill.

</project_validation>

<support_file_read_order>

1. Read architecture-rules.md for rule classes and blocking gates.
2. Read only affected topics:
   • rules/project-structure.md for scalable folders, ownership, imports, and migration.
   • rules/routing-and-navigation.md for Expo Router layouts, route groups, params, and route thinness.
   • rules/data-state-and-boundaries.md for server state, client state, DTOs, persistence, and dependency direction.
   • rules/native-platform-and-security.md for app config, permissions, secrets, storage, native code, and platform files.
   • rules/testing-and-validation.md before implementation completion.
3. Read references/official/expo-react-native-2026-08-03.md only when current SDK/API behavior affects a decision.

</support_file_read_order>

Phase	Task	Output
0	Confirm Expo mode, SDK, platforms, request scope, and side-effect gates	Scope decision
1	Inventory routes, features, shared modules, state/data, native config, tests, and dependency direction	Architecture map
2	Classify findings as Official, Safety, or Hypercore convention	Prioritized plan
3	Define target boundaries and the smallest migration slice; preserve user work	Change set
4	Implement safe reversible changes and update affected callsites/tests/config	Integrated architecture
5	Run focused then project-level checks and inspect resolved behavior	Verification evidence
6	Report decisions, versions/sources, results, and residual risks in Korean	Handoff

• Prefer src/app for routes in current Expo Router projects while keeping non-route code outside it.
• Organize growth by src/features/<domain> and narrowly scoped src/shared/*; avoid dumping domain behavior into global components, hooks, utils, or services buckets.
• Keep route files composition-oriented; business rules and reusable data access belong to feature/application layers.
• Keep TypeScript strict, validate untrusted runtime data at boundaries, and avoid any and unchecked casts.
• Separate server state, client UI state, form state, and persisted device state by ownership and lifecycle.
• Treat EXPO_PUBLIC_* as public; store small secrets only in secure platform-backed storage and never bundle server secrets.
• Make platform divergence explicit with .ios.ts(x) / .android.ts(x) or a small adapter when behavior truly differs.
• Use the installed SDK and expo install compatibility rather than guessing package versions.

• Inventing project commands, packages, native capabilities, API contracts, or environment variables.
• A universal folder template applied without inspecting project scale and existing conventions.
• Domain features importing route files, UI importing infrastructure internals, or broad barrel files that create cycles.
• Secrets in source, app config extra, EXPO_PUBLIC_*, logs, AsyncStorage, or client bundles.
• Running package installs, prebuild --clean, EAS builds/updates/submits, signing, or store publication without explicit authorization.
• Treating Expo Go success as proof that development/standalone builds, permissions, config plugins, or native modules work.
• Unbounded refactoring or migration without a verified incremental boundary.

• Expo mode, SDK, React Native, Router, package manager, platforms, and native-directory ownership are identified.
• At least 3 positive, 2 negative, and 1 boundary trigger examples remain present.
• Route files are thin and non-route modules do not live under app/src/app.
• Dependency direction and feature/shared ownership are explicit; cycles and unsafe barrels are absent.
• Runtime inputs, environment, persistence, permissions, and secure storage follow boundary rules.
• Android/iOS changes are checked independently where behavior or config differs.
• Relevant typecheck, lint, tests, Expo diagnostics, resolved config, and build checks ran or are explicitly reported as unavailable.
• English/Korean skill files retain equivalent trigger, authority, workflow, safety, and completion semantics.
• Current official claims cite the dated reference; source dates are not in the future.
• Completion records Claim -> Risk -> Evidence -> Verification -> Result -> Caveat and decides ship, iterate, caveated ship, or block.