168 lines
5.6 KiB
Markdown
168 lines
5.6 KiB
Markdown
# 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.
|