admin/docs/apps/admin/architecture/layers/app.md

App Layer

Purpose

The app layer is the composition root of the Admin application. It owns the concerns that exist once for the whole app and coordinates lower-level layers and feature modules without containing feature business logic.

Global React providers belong inside app/providers/. They are an implementation detail of the app layer, not a separate architectural layer.

Responsibilities

• Compose global React providers in one root component.
• Configure application-wide settings and environment-derived values.
• Initialize internationalization and global styles.
• Define top-level routing and connect routes registered by modules.
• Provide application layouts, navigation, and menu composition.
• Register core, project, and development modules with the app shell.

Current Structure

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

The exact files may evolve, but their ownership should remain app-wide. A concern used by only one feature belongs to that feature module instead.

Global Providers

app/providers/AppProviders.tsx is the single provider composition point. The current provider tree supplies:

• TanStack Query configuration and error handling
• authentication context from the Auth core module
• application settings
• shared tooltip and notification UI
• theme state
• internationalization and text direction
• React Router with the configured base URL

Routing

app/routing/ owns top-level route composition. It connects the application shell to routes contributed by registered modules. Feature pages and route-specific logic remain inside their owning modules.

Configuration and Internationalization

• app/config/ owns global settings, application metadata, and configuration types.
• app/i18n/ owns supported languages, translated messages, and i18n configuration.
• Environment access should be centralized through app configuration instead of being repeated throughout feature code.

Layouts and Global CSS

app/layouts/ contains the Admin shell variants. app/css/ contains global styles, layout styles, and app-wide overrides for third-party components. Feature-specific styles should stay with the feature that owns them.

Module Registration

app/services/modules/ integrates modules into the application through their routes, menus, and translated messages. It is integration code owned by the app shell; module implementation details remain under core/, modules/, or devtools/.