docs: update README with project architecture details and submodule management instructions

README.md

@@ -1,56 +1,143 @@
-# New FISApp UI
-Code repository for FISApp UI project.    
-Demo Site: [Financial Information System](https://fist.swopt.com)    
-Current Angular Version: ^21.1.2    
-**requires NodeJS version ^20.19.0 || ^22.12.0 || ^24.0.0   
+# FISApp UI
 
-## Getting Started
-After cloning this project, checkout your project to the `dev` branch by running `git checkout origin/dev`.        
-    
-Initialize project by running `./init-project`. This will automatically install all required dependencies.   
+Angular 21 SPA — multi-tenant dashboard with a lazy-loaded **PalmVision** sub-app for MPOB-standard palm oil fruit bunch (FFB) ripeness detection.
 
-It is recommended to run the `./clean-project` script whenever a new library is added.    
-    
-If you encounter the following error while trying to run `ng serve`, 
-please run `./clean-project`.    
-Alternatively, you may delete all contents of this folder: [your_project_directory]/src/dependencies/angularlib/node_modules/@angular    
-You may do so by running    
-Windows powershell:    
-`rm -r -force src/dependencies/angularlib/node_modules/@angular`    
-Linux/MacOS:    
-`rm -rf src/dependencies/angularlib/node_modules/@angular`    
+**Current Angular version:** ^21.1.2  
+**Required Node.js:** `^20.19.0 || ^22.12.0 || ^24.0.0`
+
+---
+
+## Setup
+
+### 1. Clone the repository (with submodules)
+
+This project uses Git submodules for shared in-source dependencies (`angularlib`, `dp-ui`, `fis`). Clone recursively to pull them in one step:
+
+```bash
+git clone --recurse-submodules https://<your-remote>/fisapp-ui.git
+cd fisapp-ui
+```
+
+# Clone with submodules
+``` for termux
+git clone --recursive <your-repo-url>
+```
+
+If you already cloned without `--recurse-submodules`, initialise and fetch the submodules manually:
+
+```bash
+git submodule update --init --recursive
+```
+
+To pull the latest commits for all submodules after an upstream update:
+
+```bash
+git submodule update --remote --recursive
 ```
-[ERROR] TS-993004: Unable to import class CommonModule.
-  The symbol is not exported from [your_project_directory]/src/dependencies/angularlib/node_modules/@angular/common/index.d.ts (module '@angular/common'). [plugin angular-compiler]    
-```    
 
-## Project Dependencies
-Project dependencies can be found in `src/dependencies`  
-`angularlib` - SWOPT's angular library for commonly used components    
-`dp-ui` - Domain Proxy library (UI version)      
-etc...    
-![Project dependencies location](https://cdn.swopt.com/media/images/ng-template/eg001.png)
+### 2. Install dependencies
+
+```bash
+npm install
+```
 
-## Development server
+> Run `npm run clean` whenever a new library is added or if you hit Angular cache issues.
 
-Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.
+### 3. Start the dev server
 
-## Code scaffolding
+```bash
+npm start
+# → http://localhost:4200
+```
 
-Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
+The frontend connects to the NestJS backend at `https://localhost:3000`. Start the backend first:
 
-## Build
+```bash
+cd ../server-desktop && npm install && npm run start:dev
+```
 
-Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
+---
 
-## Running unit tests
+## Submodules
 
-Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
+| Alias | Path | Branch |
+|---|---|---|
+| `angularlib/*` | `src/dependencies/angularlib` | `swopt-eLeave` |
+| `dp-ui/*` | `src/dependencies/dp-ui` | `master` |
+| `fis/*` | `src/dependencies/fis` | `swopt-eLeave` |
+
+`fis-commons` is CDN-hosted and requires no local checkout.
+
+---
+
+## Common Commands
+
+```bash
+npm start                   # Dev server at 0.0.0.0:4200
+npm run build               # Production build → dist/fisapp-ui
+npm run build:dev           # Dev build → dist/dev
+npm run build:prod          # Prod build → dist/rc
+npm run build:leave:prod    # Leave-module variant
+npm run build:quot:prod     # Quotation variant
+npm run build:maf:quot:prod # MAF quotation variant
+npm run test                # Karma + Jasmine unit tests
+npm run clean               # Clear Angular + npm caches
+```
 
-## Running end-to-end tests
+---
 
-Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.
+## Troubleshooting
+
+### `[ERROR] TS-993004: Unable to import class CommonModule`
+
+A stale Angular build cache inside the `angularlib` submodule. Run:
+
+```bash
+npm run clean
+```
+
+Or delete the conflicting folder directly:
+
+```powershell
+# Windows PowerShell
+rm -r -force src/dependencies/angularlib/node_modules/@angular
+```
+
+```bash
+# Linux / macOS
+rm -rf src/dependencies/angularlib/node_modules/@angular
+```
+
+---
+
+## PalmVision Sub-App
+
+Lazy-loaded at `/src.palm.vision`. Provides three inference engines:
+
+| Engine | Mode key | Description |
+|---|---|---|
+| Browser ONNX WASM | `local-onnx` | Runs YOLOv8 (`best.onnx`) via `onnxruntime-web` in a Web Worker |
+| Browser TFLite WASM | `local-tflite` | Runs `best_float16.tflite` via TFLite Web API in a Web Worker |
+| NestJS Remote | `remote` | Offloads inference to the `server-desktop` backend over WebSocket |
+
+Connection config: `src/src.palm.vision/config/config.json`
+
+```json
+{ "connection": { "uacp": "https://localhost:3000", "uacp_ws": "wss://localhost:3000/socket.io", "uacpEmulation": "on" } }
+```
+
+Detection classes (MPOB standard): `Ripe`, `Unripe`, `Underripe`, `Overripe`, `Abnormal`, `Empty_Bunch`
+
+---
+
+## Code Scaffolding
+
+```bash
+ng generate component component-name
+ng generate directive|pipe|service|class|guard|interface|enum|module
+```
 
-## Further help
+## Further Help
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.
+- Angular CLI: `ng help` or the [Angular CLI docs](https://angular.dev/tools/cli)
+- Project architecture: see [`CLAUDE.md`](CLAUDE.md)