diff --git a/AGENTS.md b/AGENTS.md index 139dfc66f..299a387fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,15 +29,75 @@ 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 @@ -45,7 +105,7 @@ enforced server-side (see `security.md`). - **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 `
  • ` — 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 index 7a73788ec..7b3689436 100644 --- 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 index 0baebd3b7..62f900ba8 100644 --- 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`.