# 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

```plaintext
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/`.