apache · zhangxinyao88 · Sep 6, 2026 · Sep 6, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -29,23 +29,83 @@ Angular 22 standalone single-page application — the back-office UI for the Apa
 core banking platform. It communicates with the Fineract REST API; all authorization is
 enforced server-side (see `security.md`).
 
+## Start here
+
+- `README.md` is the human-facing overview, local quick start, and deployment entry point.
+- `CONTRIBUTING.md` defines contributor expectations, commit signing, and the UI-versus-backend
+  issue boundary.
+- `DOCS/CI_CHECKS.md` is the source of truth for CI jobs and how to reproduce them locally.
+- `DOCS/E2E_TESTING.md` explains the mocked and real-Fineract Playwright projects.
+- `DOCS/adr/` records architectural constraints. Read the relevant ADR before changing adapters,
+  generated API use, or the test setup.
+- `security.md` describes the trust boundaries. A UI visibility check is never authorization.
+
+## Setup and everyday workflow
+
+Use npm and the committed lockfile. The project requires Node `>=22.22.3`; do not require a global
+Angular CLI.
+
 ## Common commands
 
-| Task       | Command                              |
-| ---------- | ------------------------------------ |
-| Dev server | `npm start`                          |
-| Unit tests | `npm test -- --watch=false` (Vitest) |
-| Lint       | `npm run lint`                       |
-| Format     | `npm run format`                     |
-| Prod build | `npm run build`                      |
+| Task                                     | Command                                   |
+| ---------------------------------------- | ----------------------------------------- |
+| Install a clean dependency tree          | `npm ci`                                  |
+| Generate local HTTPS certificates (once) | `./scripts/setup-ssl.sh`                  |
+| Dev server                               | `npm start`                               |
+| App unit tests (Vitest)                  | `npm run test:unit`                       |
+| Microfrontend unit tests                 | `npm run test:mfe`                        |
+| Mocked Playwright tests                  | `npm run test:e2e -- --project=mocked`    |
+| Type-check E2E specs                     | `npm run typecheck:e2e`                   |
+| Lint / prune resolved suppressions       | `npm run lint` / `npm run lint:prune`     |
+| Check / apply formatting                 | `npm run format:check` / `npm run format` |
+| Production build                         | `npm run build`                           |
+
+`npm start` and Playwright use HTTPS. `ssl/localhost.crt` and `ssl/localhost.key` are local-only
+and git-ignored; create them before the first local run. Mocked Playwright specs need no Fineract
+server. Run the backend project only when the change needs real integration coverage; its Docker
+workflow is documented in `DOCS/E2E_TESTING.md`.
+
+## Repository map
+
+| Path                | Purpose                                                                  |
+| ------------------- | ------------------------------------------------------------------------ |
+| `src/app/features/` | Banking workflows, grouped by domain.                                    |
+| `src/app/core/`     | Cross-cutting services, adapters, API surface, configuration, and icons. |
+| `src/app/shared/`   | Reusable components, directives, and pipes.                              |
+| `src/app/api/`      | Generated OpenAPI client; never hand-edit it.                            |
+| `src/app/testing/`  | Shared unit-test providers, adapter fakes, and mocks.                    |
+| `e2e/`              | Playwright specs and helpers.                                            |
+| `deploy/`           | Container image, NGINX proxy, and Compose stacks.                        |
+| `DOCS/`             | Contributor, CI, integration, and architecture documentation.            |
+
+## Change-directed validation
+
+Start with the checks relevant to the files changed, then run the normal local baseline before
+opening a PR. `DOCS/CI_CHECKS.md` lists every CI job.
+
+- Application logic: `npm run lint`, `npm run test:unit`, and `npm run build`.
+- Templates, translations, or icons: also run `npm run i18n:check`, `npm run check:icons`, and
+  `npm run check:a11y-names`.
+- Routes, navigation, RBAC, or branding: run the corresponding `check:*` scripts described in
+  `DOCS/CI_CHECKS.md` and add/update focused coverage.
+- Browser-facing changes: run the affected mocked Playwright spec, for example
+  `npx playwright test --project=mocked e2e/client.spec.ts`; use a real backend only for journeys
+  that cannot be expressed with request mocks.
+- API-spec or generated-client changes: run `npm run verify-api-client` (requires Java 17) and
+  `npm run api:surface`. Regenerate from the spec; do not edit `src/app/api/` manually.
+- New dependency or deployment change: run `bash scripts/check-license.sh` and consult
+  `DOCS/LINT_POLICY.md` and `security.md`.
+
+`eslint-suppressions.json` is a shrinking baseline. Do not edit it by hand; after moving or fixing
+source, run `npm run lint:prune` and commit only the removals it produces.
 
 ## Conventions
 
 - **Standalone components/directives** (no NgModules). Services are `@Injectable({ providedIn: 'root' })`.
 - **Signals** for reactive state (`signal()`, `computed()`, `asReadonly()`); see
   `src/app/core/services/config.service.ts` for the canonical pattern.
 - Every source file carries the ASF Apache-2.0 license header.
-- `localStorage` keys are snake*case, `fineract*`-prefixed.
+- `localStorage` keys are `snake_case`, `fineract_`-prefixed.
 
 ## UI components — Ionic
 
@@ -90,12 +150,23 @@ Third-party surfaces the application must be able to replace are reached through
 - In specs, use `provideFakeAdapters()` from `src/app/testing/adapters.ts` rather than mocking
   the library.
 
+## Security and generated boundaries
+
+- Keep browser API calls on the configured, same-origin path. Changing an external API destination
+  requires coordinated changes to the CSP and `allowedApiOrigins`; see `README.md` and `security.md`.
+- Do not place credentials, API tokens, or real customer data in source, fixtures, screenshots, or
+  Playwright recordings. The demo credentials in the documented local stack are for that stack only.
+- `RBAC_ENABLED` and structural directives control what the UI presents. Fineract remains the
+  authorization boundary, so do not treat a hidden route or disabled action as a security fix.
+- Treat `src/app/api/` as generated output. Update `public/api/fineract.json` or generator options,
+  regenerate, and let the drift check prove the result.
+
 ## RBAC and feature flags
 
-### `environment.rbacEnabled`
+### `rbacEnabled`
 
-A build-time boolean read directly from `src/environments/environment.ts`,
-`environment.prod.ts`, and `environment.sandbox.ts` (default: `true`).
+A runtime boolean loaded from `config.json` by `ConfigService` (default: `true`). A deployment can
+change it without rebuilding the application.
 
 - **`true`** — the sidebar filters navigation by user permissions and institution config;
   permission/institution directives enforce their checks.
@@ -129,3 +200,13 @@ institution type (`'mfis' | 'cb' | 'cu' | 'universal'`) to `localStorage`
 `*appInstitutionFeature`, and gates high-value groups (Admin, Accounting, Security, Settings,
 System) with `*appHasPermission`. Additional nav items can be gated by adding the appropriate
 directive to their `<li>` — the pattern is intentionally incremental.
+
+## Pull requests
+
+- Branch from `main`, keep the change focused, and link the related GitHub issue in the PR body.
+- New source files need the ASF Apache-2.0 header. Commit signing is required for merging; see
+  `CONTRIBUTING.md`.
+- Explain the user-facing or behavioral change and name the checks actually run. Do not claim an
+  E2E or backend validation that was not performed.
+- Avoid unrelated refactors in a feature or migration PR. If a check exposes pre-existing work,
+  describe it separately rather than folding it into the change.
diff --git a/README.md b/README.md
@@ -103,46 +103,58 @@ System admins handle security, audit, and infrastructure. The UI supports:
 
 ## Prerequisites
 
-- **Node.js** (v22 or later recommended) and **npm** or **yarn**
-- **Angular CLI** (`npm i -g @angular/cli`)
-- **Apache Fineract** instance (e.g. via Docker: `docker run -d -p 8443:8443 apache/fineract:latest`)
-- Access to Fineract REST API (default demo: `mifos` / `password` on `https://localhost:8443/fineract-provider/api/v1`)
+- **Node.js** `>=22.22.3` and npm. The repository includes the Angular CLI, so a global install is not needed.
+- For local HTTPS development, [`mkcert`](https://github.com/FiloSottile/mkcert) to generate the ignored
+  `ssl/localhost.*` files once.
+- A Fineract instance for manual work or real-backend E2E tests. Mocked unit and Playwright tests do
+  not need one.
 
 ---
 
 ## Getting Started
 
-### Development
+### Quick start
 
 ```bash
-# Install dependencies
-npm install
+# Install exactly what the lockfile specifies
+npm ci
 
-# Configure API base URL (e.g. in environment files)
-# Default: https://localhost:8443/fineract-provider/api/v1
+# Generate local-only HTTPS certificates (first run)
+./scripts/setup-ssl.sh
 
 # Run development server
 npm start
 ```
 
-Access the app at `http://localhost:4200` (or the configured port).
+The app is available at `https://localhost:4200`. The development proxy keeps API traffic same-origin;
+see [Project Setup Guide](SETUP.md) to connect a local Fineract instance or a sandbox.
 
-### Testing & Quality
+### Validate a change
 
 ```bash
 # Run unit tests (Vitest)
 npm test -- --watch=false
 
-# Run end-to-end tests (Playwright)
-npm run test:e2e
+# Install the Chromium binary used by the next command (first run)
+npx playwright install chromium
+
+# Run the fast, mocked browser tests (no Fineract backend required)
+npm run test:e2e -- --project=mocked
 
 # Run linting
 npm run lint
 
-# Format code
-npm run format
+# Check formatting without modifying files
+npm run format:check
+
+# Production build
+npm run build
 ```
 
+For real-backend E2E, a local Docker stack, and focused Playwright runs, see
+[E2E testing](DOCS/E2E_TESTING.md). The complete PR check list and commands for reproducing failures
+are in [CI checks](DOCS/CI_CHECKS.md).
+
 ### Configuration
 
 - **API Base URL:** Point to your Fineract instance (e.g. `https://your-fineract-host:8443/fineract-provider/api/v1`)
@@ -223,6 +235,11 @@ For more information on contributing, setting up the project, and our coding sta
 - [Contributing Guide](CONTRIBUTING.md)
 - [Project Setup Guide](SETUP.md)
 - [Code Style Guide](STYLE.md)
+- [Agent guidance](AGENTS.md)
+- [CI checks](DOCS/CI_CHECKS.md)
+- [E2E testing](DOCS/E2E_TESTING.md)
+- [Architecture decisions](DOCS/adr/)
+- [Security model](security.md)
 - [Fonts](DOCS/FONTS.md)
 - [Lint and dependency-licence policy](DOCS/LINT_POLICY.md)
 - [Releasing](RELEASING.md)

diff --git a/SETUP.md b/SETUP.md
@@ -23,9 +23,12 @@ This guide provides instructions for setting up the Fineract Backoffice UI devel
 
 ## Prerequisites
 
-- **Node.js**: LTS version (v22.x or later).
-- **npm**: v10.x or later.
-- **Angular CLI**: v20.x or later.
+- **Node.js**: `>=22.22.3`.
+- **npm**: the package manager used by the committed lockfile.
+- **mkcert**: required only for the local HTTPS development server.
+
+The Angular CLI is a project dependency. Use the repository scripts instead of installing a global
+CLI, which can be a different major version.
 
 ## Installation
 
@@ -38,57 +41,59 @@ This guide provides instructions for setting up the Fineract Backoffice UI devel
 
 2.  **Install dependencies**:
     ```bash
-    npm install
+    npm ci
     ```
 
-## Local Helper Scripts
-
-For convenience, the following scripts are provided for local development (Linux/macOS):
-
-- **`./run-local.sh`**: One-step setup. Installs dependencies, generates local SSL certificates (using OpenSSL), and starts the server in HTTPS mode.
-- **`./cleanup-local.sh`**: Safely stops background Angular processes and removes temporary build/SSL artifacts.
-
 ---
 
 ## Development
 
 1.  **Secure Development (SSL)**:
-    Since Fineract sandboxes often require HTTPS, run the following to set up local trusted certificates (requires `mkcert`):
+    The development server is configured for HTTPS. Generate trusted local certificates once
+    (requires `mkcert`):
 
     ```bash
     ./scripts/setup-ssl.sh
     ```
 
 2.  **Run the application**:
-    - **Local Development**:
-      ```bash
-      npm start
-      ```
-    - **Mifos Sandbox**:
-      ```bash
-      npm run start:sandbox
-      ```
-      Access the UI at `http://localhost:4200` (or `https://localhost:4200` if using SSL).
-
-3.  **Connecting to a Sandbox**:
-    Update `src/environments/environment.ts` with your sandbox URL:
-
-    ```typescript
-    fineractApiUrl: 'https://demo.mifos.io/fineract-provider/api/v1';
+
+    ```bash
+    npm start
     ```
 
+    Access the UI at `https://localhost:4200`.
+
+3.  **Connect to Fineract**:
+
+    Configuration is loaded from `public/config.json` at runtime; do not edit an environment file
+    to configure a deployment.
+
+    For a local Fineract instance listening on `https://127.0.0.1:8443`, choose **Local Proxy
+    Server** (`/fineract-provider/api/v1`) on the sign-in page. `proxy.conf.json` forwards that path
+    to Fineract and avoids cross-origin requests.
+
+    For a deployed or remote instance, set `fineractApiUrl` in `config.json`. An absolute URL must
+    also appear in `allowedApiOrigins`, because the selected endpoint receives the user's
+    credentials. The same-origin `/api/v1` path used by the Docker deployment is the preferred
+    production setup; see `README.md`.
+
 4.  **Run unit tests**:
 
     ```bash
-    npm run test
+    npm test -- --watch=false
     ```
 
 5.  **Run end-to-end tests**:
 
     ```bash
-    npm run test:e2e
+    npx playwright install chromium # first run only
+    npm run test:e2e -- --project=mocked
     ```
 
+    The mocked project needs no Fineract instance. See `DOCS/E2E_TESTING.md` for the Docker-backed
+    project and focused runs.
+
 6.  **Run linting**:
 
     ```bash
@@ -104,7 +109,6 @@ For convenience, the following scripts are provided for local development (Linux
 
 1.  **Build and start container**:
     ```bash
-    cd deploy
-    docker-compose up --build
+    docker compose -f deploy/docker-compose.yml up --build
     ```
     Access the UI at `http://localhost:8080`.