# Bharat ERP — Architecture Guide

## Overview

Bharat ERP Phase 1 is an **Asset Management System (AMS)** built with Flutter for Web, Android, and iOS. The architecture is designed to be **ERP-ready** — new modules (Inventory, HR, Finance, etc.) can be plugged in without restructuring the foundation.

## Tech Stack

| Layer | Technology |
|-------|------------|
| Framework | Flutter 3.x |
| State Management | Riverpod |
| Routing | GoRouter |
| HTTP Client | Dio |
| Models | Freezed + JsonSerializable |
| UI | Material 3 + Responsive Framework |
| Local Storage | SharedPreferences + FlutterSecureStorage |

## Project Structure

```
lib/
├── main.dart                 # Entry point
├── app.dart                  # Root widget, theme, router
│
├── core/                     # Cross-cutting concerns
│   ├── constants/            # API paths, app constants, enums
│   ├── errors/               # Failure types, exceptions
│   ├── network/              # Dio client, interceptors
│   ├── theme/                # Theme engine, branding
│   └── utils/                # Helpers, validators, extensions
│
├── shared/                   # Shared across modules
│   ├── models/               # Common DTOs (pagination, API response)
│   ├── providers/            # Global providers (auth, theme, company)
│   ├── routes/               # GoRouter configuration
│   └── widgets/              # Reusable UI components
│
└── modules/                  # Feature modules (Clean Architecture)
    ├── auth/
    ├── company/
    ├── branch/
    ├── users/
    ├── roles/
    ├── dashboard/
    ├── assets/
    └── settings/
```

## Module Structure (Clean Architecture)

Each module follows the same internal layout:

```
modules/<module>/
├── data/
│   ├── datasources/          # Remote/local data sources
│   ├── models/               # DTOs (Freezed + JSON)
│   └── repositories/           # Repository implementations
├── domain/
│   ├── entities/             # Business entities
│   ├── repositories/         # Abstract repository contracts
│   └── usecases/             # Single-responsibility use cases
└── presentation/
    ├── providers/            # Riverpod providers & notifiers
    ├── screens/              # UI screens
    └── widgets/              # Module-specific widgets
```

### Data Flow

```
Screen → Provider/Notifier → UseCase → Repository → DataSource → API
                ↑                                      ↓
                └──────────── Entity / Failure ←───────┘
```

## Multi-Company Support

- Every API request includes `X-Company-Id` header (set by auth interceptor).
- Company context is stored in `CompanyProvider` after login.
- Branch context is optional via `X-Branch-Id` header.
- Super Admin can switch companies; other roles are scoped to their company.

## Role-Based Access Control (RBAC)

### Roles

| Role | Scope |
|------|-------|
| Super Admin | All companies, all modules |
| Company Admin | Single company, all modules |
| Asset Manager | Single company, asset operations |
| Employee | Single company, read + own allocations |

### Permissions

`create`, `read`, `update`, `delete`, `export`, `approve`

Permissions are checked via `PermissionGuard` widget and `hasPermission()` utility. The dynamic sidebar menu is built from the user's role permissions returned by the API.

## Authentication Flow

1. User submits credentials → `POST /auth/login`
2. API returns JWT access + refresh tokens
3. Tokens stored in FlutterSecureStorage
4. Dio interceptor attaches `Authorization: Bearer <token>`
5. On 401, refresh token flow is attempted
6. On refresh failure, user is redirected to login

## Theme Engine

- **Appearance modes**: Light, Dark, System
- **Company branding**: Logo, primary color, secondary color
- Theme persisted in SharedPreferences
- `AppTheme` generates Material 3 ColorScheme from branding colors

## Responsive Breakpoints

| Breakpoint | Width | Layout |
|------------|-------|--------|
| Mobile | < 600px | Bottom nav, single column |
| Tablet | 600–1024px | Collapsible sidebar |
| Desktop | > 1024px | Persistent sidebar |

## API Conventions

- Base URL: configured via `.env`
- All responses wrapped in `ApiResponse<T>`
- Pagination via `PaginatedResponse<T>` with `page`, `limit`, `total`
- Errors return `{ "message": "...", "code": "..." }`

## Database Tables (Backend Reference)

```
companies, branches, users, roles, permissions, role_permissions,
asset_categories, assets, asset_allocations, asset_allocation_history,
asset_maintenance, asset_disposal, notifications, audit_logs
```

## Development Order

| Week | Focus |
|------|-------|
| 1 | Project setup, theme, auth, API layer |
| 2 | Company, branch, users, roles |
| 3 | Asset categories, master, allocation |
| 4 | Maintenance, disposal, QR |
| 5 | Dashboard, reports, audit, settings |
| 6 | Testing, optimization, deployment |

## Adding a New Module

1. Create `modules/<name>/` with data/domain/presentation layers
2. Add route constants in `core/constants/route_constants.dart`
3. Register routes in `shared/routes/app_router.dart`
4. Add menu item in `shared/widgets/app_shell.dart` with permission check
5. Create repository interface in domain, implementation in data
6. Wire providers in presentation layer

## Code Generation

```bash
dart run build_runner build --delete-conflicting-outputs
```

Generates `.freezed.dart` and `.g.dart` files for models.