bharat_erp/docs/ARCHITECTURE.md

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

dart run build_runner build --delete-conflicting-outputs

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