zero-fucks-given/docs/architecture/react-frontend/layers/app.md

App Layer

The composition root: owns concerns that exist once for the whole app and coordinates layers and modules without containing feature business logic. It composes global providers, configures app-wide settings and environment values, initializes i18n and global styles, defines top-level routing, provides layouts and menus, and registers core/project/development modules.

app/
├── config/                    # global settings, environment values, and config types
├── css/                       # global styles and app-level third-party overrides
├── i18n/                      # languages, messages, and internationalization config
├── layouts/                   # top-level Admin layout variants
├── providers/                 # providers composed once for the entire application
│   ├── AppProviders.tsx
│   ├── I18nProvider.tsx
│   ├── QueryProvider.tsx
│   ├── SettingsProvider.tsx
│   └── ThemeProvider.tsx
├── routing/
│   ├── AppRouting.tsx
│   └── AppRoutingSetup.tsx
├── services/
│   └── modules/               # module registry, routes, menus, and messages
└── menu.tsx                   # app-level menu composition

Files may evolve, but ownership stays app-wide — a concern used by only one feature belongs to that feature module.

Notes

• Providers — app/providers/AppProviders.tsx is the single composition point: TanStack Query, auth context (from the Auth core module), settings, tooltip/notification UI, theme, i18n and text direction, React Router.
• Routing — app/routing/ composes top-level routes from routes contributed by registered modules; feature pages stay in their modules.
• Config & i18n — centralize environment access through app/config/ instead of repeating it in feature code; app/i18n/ owns languages and messages.
• Layouts & CSS — app/layouts/ holds the Admin shell variants, app/css/ global and third-party overrides; feature styles stay with the feature.
• Module registration — app/services/modules/ wires modules in through their routes, menus, and messages; module implementation stays under core/, modules/, or devtools/.