frontend-architecture

What it does

It prescribes a portable, framework-agnostic architecture for React or React Native frontends. It organizes apps into feature modules inside a modules/{feature}/ directory, with a PUBLIC BARREL at modules/{feature}/index.ts that re-exports pages, data hooks, stores, and types. Pages are directories (pages/{page}/) containing a page component, styles file, an index.ts, and optionally page-scoped components, hooks, and data. It enforces a strict split between server state (in a query/cache layer) and UI/client state (in a module-owned store) and requires one store unit per module. Data access goes through a single typed client in shared/api-client/, with module-specific hooks and a hierarchical key factory for cache invalidation. Styling must be co-located per page/component via a dedicated {name}.styles.ts (or equivalent) and never inline styles. Naming conventions are clearly defined (I-prefixed interfaces, kebab-case folders, PascalCase components, etc.). Framework adapters are designed to map onto Next.js App Router, React + Vite SPA, Remix, and Expo/React Native, with a library-agnostic approach to choosing state libraries.

How it works

1. Structure the code into feature modules under modules/{feature}/ with a single PUBLIC BARREL in index.ts exporting pages, data hooks, stores, and types. 2) Organize each page as a directory pages/{page}/ containing {page}.tsx, {page}.styles.ts, index.ts, and optional subfolders for page-scoped components/hooks. 3) Maintain a strict server state vs UI state split: server data via a query/cache layer, UI state in a module store. 4) Do not mirror server responses into the client store; components read server data via data hooks and UI state from store selectors. 5) Access the network only through a shared typed client in shared/api-client/. 6) Keep styling in co-located {name}.styles.ts files appropriate to the chosen styling stack; avoid inline styles. 7) Follow the naming conventions for interfaces, components, stores, hooks, and barrels. 8) Use framework adapters to map the structure to the target framework routing layer.

When to use it

Use this when you need a portable, framework-agnostic architecture style for any React or React Native frontend. It applies to Next.js (App Router), React + Vite (SPA), Remix, and Expo / React Native, and works with any state-management and styling stack. It aims to answer quickly where code lives, what can import what, and whether data is server or UI state.

What it can touch

• Modules and their public barrels: imports from "@/modules/{feature}".
• Shared data client at "shared/api-client/".
• Data hooks and state stores inside each feature (e.g., "modules/{feature}/stores/…" or equivalent per library).
• Page components, page-specific hooks, and styling files under each feature.

Caveats

• Risk: critical
• License: MIT