Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AllianceBioversityCIAT/alliance-research-indicators-client/llms.txt

Use this file to discover all available pages before exploring further.

The Alliance Research Indicators client is a role-aware Angular 19 SPA that captures structured research outcomes for the Alliance of Bioversity International and CIAT across the CGIAR ecosystem. Before making any non-trivial change, read the relevant constitutional document — the docs/ folder is the authoritative source of truth for product intent, UX rules, and technical conventions. Every contribution, whether a new feature, a UI change, or a technical refactor, follows the same workflow: consult the right document first, write a spec if needed, implement within the constraints, and keep the docs in sync with reality.

​
Contribution workflow

1

Identify the right constitutional document

Determine whether your change affects product scope, UI/UX, or technical implementation and read the corresponding document before writing any code. If your change touches multiple layers, read all relevant docs.
2

Write a spec for new features

Run /sdd-specify to generate the three-file spec scaffold under docs/specs/<domain>/<feature>/. Complete all three files — requirements.md, design.md, and task.md — before opening a pull request. Never skip the spec for user-visible features.
3

Reach for shared components and tokens

For UI work, always check the component inventory in docs/system-design/design.md §8 before building something new. Use token utility classes (.abc-*, .atc-*, .rs-*, .fs-*) and CSS variables (var(--ac-*)) rather than inventing parallel patterns.
4

Update the design doc when you deviate

If you introduce a new component, pattern, color, or spacing value not already in docs/system-design/design.md, record the decision in §12 Design Decisions in the same change. Local decisions that diverge from the global blueprint without updating it are not allowed.
5

Update the technical doc when you deviate

If you deviate from any pattern in docs/detailed-design/detailed-design.md — a new service, interceptor, state boundary, or integration — update that document in the same pull request.
6

Keep tests green and coverage above the floor

All tests must pass with npm run test. Coverage must not regress below the project floors enforced by jest.config.ts. Log open questions in the relevant doc’s “Open Questions” section, not in commit messages.
7

Follow PR and branching conventions

PR titles use <type>(<domain>): <short description> (e.g., feat(results): add bulk evidence upload). One task per PR by default. Pre-merge: CI green, bundle budget respected, manual smoke of affected golden paths. Conventions are in docs/specs/general-setup/task.md §6.

​
Constitutional documents

The four documents below form the SDD constitutional baseline. They are living documents — if reality disagrees with them, fix one or the other; never let them drift.

docs/prd.md

Product Requirements Document — problem statement, four personas (Researcher, Center Admin, MEL Regional Expert, Cross-Platform Consumer), goals, KPIs (M1–M8), scope, non-goals, user stories, acceptance criteria, and hard constraints C-1 through C-6.Consult before: any change that affects what the product does for users, or that touches scope, personas, or KPIs.

docs/system-design/design.md

UI/UX Blueprint — experience principles, information architecture, five primary user flows, 22-screen inventory, navigation model, layout patterns, design tokens, component inventory, responsive behavior, accessibility, dark mode, and design decision record.Consult before: any UI/UX change — new screen, new pattern, new color or spacing, new modal, or theme work.

docs/detailed-design/detailed-design.md

Technical Blueprint — system overview, domain modules, data model, API contracts (MainResponse<T> envelope, three services, three interceptors), state boundaries (signals + RxJS, no NgRx), integrations (Cognito, CLARISA, file-manager, text-mining, WebSocket, analytics), security, error handling, testing strategy, and constraints.Consult before: any technical change — new service, interceptor, route, dependency, integration, or change to state, auth, or error patterns.

docs/specs/general-setup/

SDD Methodology Templates — requirements.md, design.md, and task.md format definitions for module specs. These templates are consumed by /sdd-specify, /sdd-execute, /sdd-validate, and /sdd-test.Consult before: running /sdd-specify for any new feature or module.

​
Hard constraints

These constraints bind every change. Updating them requires updating docs/prd.md §8.3 itself.
C-1 — Stack lock. The stack is Angular 19 + PrimeNG 19. No framework migration. No mixing of other component libraries.
C-2 — Auth lock. Authentication is AWS Cognito + JWT. No alternative identity providers in this client. Never bypass jWtInterceptor. Tokens stay in localStorage and cache signals; never log or send them to analytics SDKs.
C-3 — Controlled vocabularies. All controlled vocabularies (institutions, countries, regions, SDGs, levers, impact areas, languages, delivery modalities, session types) come from CLARISA. No parallel taxonomies in interfaces or component dropdowns. Free text for CLARISA-managed fields is a defect.
C-4 — Accessibility floor. Every changed screen must meet WCAG 2.1 AA. This means: keyboard reachability, visible focus rings, proper <label> or aria-label on all inputs, color contrast ≥ 4.5:1 for body text, status communicated non-visually (icon + text, not color alone), and prefers-reduced-motion respected.
C-5 — Bundle budgets. Production bundles must respect angular.json budgets: initial chunk ≤ 3 MB error / 2 MB warning; component styles ≤ 8 kB / 4 kB. Running ng build must not warn beyond the established baseline.
C-6 — Lazy standalone components. All new features are lazy-loaded standalone components registered via loadComponent in app.routes.ts. No NgModules.

​
Spec taxonomy

Spec folders under docs/specs/ mirror the domain modules described in docs/detailed-design/detailed-design.md §2. Every feature spec lives inside its domain folder as a kebab-case slug containing three files. 
docs/specs/
├── general-setup/       ← methodology templates (requirements.md, design.md, task.md)
├── results/             ← result lifecycle work (11 metadata tabs)
├── indicators/          ← indicator catalog
├── projects/            ← projects and project detail
├── dashboard/           ← analytics and charts
├── notifications/       ← real-time feed
├── administration/      ← center-admin tooling (bulk upload, SDG management)
├── auth/                ← Cognito, JWT, guards
├── shared/              ← cross-cutting shared components and services
└── platform/            ← shell, navbar, sidebar
Each feature spec is a slug folder (kebab-case) containing:
FilePurpose
requirements.mdWhat to build — testable statements, acceptance criteria, persona linkage, PRD cross-reference
design.mdHow to build it — component architecture, API contracts, state boundaries, form design, security, error handling, testing strategy
task.mdExecution units — dependency graph, per-task touches, AC IDs discharged, done criteria
Requirement IDs (REQ-<DOMAIN>-<NN>) and task IDs (T-<DOMAIN>-<NN>) are immutable once published. Requirements may be marked deprecated but their IDs cannot be reused or renumbered.

​
Writing good requirements

  • One requirement = one testable statement. Write “The system shall…” or “The user can…”.
  • Outcome, not implementation. “User can attach a PDF up to 50 MB” — not “We use FormData with multipart/form-data”.
  • Acceptance criteria are mandatory. Every requirement needs at least one AC that a reviewer can evaluate as pass/fail without ambiguity.
  • Reference the PRD. Each requirement traces back to a persona (PRD §3) and at least one goal (PRD §4).
  • Open questions, not silent guesses. If something is unknown, log it under §10 Open Questions in the spec.

​
Quick rules summary

SituationRule
Adding a new screenRead system-design §2–§6 first; add a spec; use loadComponent
Adding a new serviceRead detailed-design §4–§6; extend ApiService; always handle MainResponse<T>
Adding a new formUse reactive forms; wrap PrimeNG inputs via custom-fields.scss
Adding a new color or spacingUse an existing token or utility class; never hardcode hex
Adding a new modalRoute through all-modals host + modal wrapper
Touching CLARISA-sourced dropdownsConfirm CLARISA is the source; never add a parallel list
Touching authNever bypass jWtInterceptor; no new token persistence without justification
Open questionsFile them in the relevant doc’s “Open Questions” section

Build docs developers (and LLMs) love

Get started for freeTalk to us