Managing Agricultural Research for Learning and Outcomes
MARLO is an open-source, web-based research management platform that supports the full Planning, Monitoring, Reporting, and Learning (PMRL) cycle of complex multi-country, multi-stakeholder research programs. Originally built within the CGIAR system and now actively maintained by the IBD Team at the Alliance of Bioversity International and CIAT, MARLO is the system of record for annual planning, deliverables, innovations, outcome impact case reports (OICRs), and indicator contributions across one or more research programs.
This repository hosts the AICCRA production line of MARLO. The platform has been deployed at scale on programs such as CCAFS (2017+) and AICCRA (2021–present), where it powered planning and reporting for 11 clusters across multiple African countries and supported the generation of 1,440+ knowledge products with 95%+ open-access compliance and 92%+ quality ratings.
MARLO replaces the spreadsheets, email chains, and fragmented reporting that complex research programs typically rely on. It provides:
- A single, phase-aware system of record (POWB / UpKeep / Annual Report).
- Embedded quality assurance with structured reviewer feedback.
- Built-in Open Access and FAIR compliance tracking.
- A multi-tenant model for running multiple Programs / Platforms / Centers on one platform.
- An analytics path through Microsoft Fabric (Bronze / Silver / Gold) and Power BI.
- AI-augmented services (Text Mining, Reports Generator, Chatbot) that consume MARLO data without bypassing its governance.
- Audit-friendly forward-only phase replication: past data is immutable, future data inherits planned changes.
For the full product framing, see docs/prd.md.
- Annual Work Plan and Budget (AWPB) — planning per cluster / project.
- Progress Monitoring — continuous, intra-year tracking.
- Annual Reporting (AR) — narrative + structured indicators + cluster synthesis.
- Deliverables Management — full lifecycle, Open Access, FAIR principles.
- Innovation Tracking — Scaling Readiness 0–9, typology, geographic tagging.
- Outcome Impact Case Reports (OICRs) — structured documentation with maturity classification.
- Quality Assurance — structured feedback workflows between reviewers and implementers.
- Funding & Partner Management — CLARISA-integrated.
- Impact Pathway Management — SLOs, IDOs, cross-cutting issues.
- Business Intelligence — embedded Power BI dashboards (results, QA, completeness, public).
- AI Services — text mining, narrative generation, conversational data exploration (AWS Bedrock + Claude + Titan + OpenSearch).
- Multi-tenant Administration — onboard a new Program / Platform / Center with its own roles, phases, partners, locations, and per-program feature flags ("specificities").
| Concern | Technology |
|---|---|
| Language | Java (8 and 17 branches coexist) |
| Web framework (internal flows) | Apache Struts 2 (≥ 6.4.0) |
| Web framework (REST API) | Spring MVC under /api/* (Spring ≥ 5.3.39) |
| ORM | Hibernate 5.4.x |
| Database | MySQL (AWS RDS in production) |
| Connection pool | HikariCP (≥ 5.x) |
| Servlet container | Apache Tomcat 9 (≥ 9.0.96) |
| Templating | FreeMarker (.ftl) |
| Build | Apache Maven (multi-module) + Grunt (frontend assets) |
| DB migrations | Flyway |
| Security | Apache Shiro 1.13.0 + CGIAR Active Directory |
| Dependency injection | Google Guice + Spring |
| API docs | Springdoc OpenAPI |
| Frontend assets | Bower (jQuery, Bootstrap, DataTables, Chosen, Pickadate, Trumbowyg, Cytoscape, Font Awesome, etc.) |
| Real-time notifications | Pusher |
| Reporting / export | Pentaho Reporting, iText, Apache POI |
| Analytics | Microsoft Fabric (Lakehouse, Bronze/Silver/Gold) + Power BI |
| AI | AWS Bedrock (Claude, Titan), Amazon OpenSearch, AWS Lambda |
| CI/CD | GitHub Actions → Jenkins; SonarCloud; Snyk |
Dependency floors (post-January 2026 SETI security modernization) MUST NOT be downgraded — see docs/detailed-design/detailed-design.md §8.5.
MARLO/
├── marlo-parent/ Root Maven aggregator: dependency versions + plugin config (no executable code)
├── marlo-utils/ Pure utility classes (dates, strings, Excel/CSV/PDF, JSON helpers)
├── marlo-core/ Cross-cutting configuration: Shiro, Hibernate session factory, DB config
├── marlo-data/ Domain layer: 540+ JPA entities, Manager/ManagerImpl, DAO/MySQLDAO, audit listeners
├── marlo-web/ Web tier: Struts actions, Spring REST controllers, FTL templates, validators,
│ interceptors, JS/CSS, SQL migrations
├── docs/ Constitutional documents (PRD, system design, detailed design, spec templates)
├── reports/ai-context/ Operational runbooks for routing, save/validation, persistence, composition
├── scripts/ Run scripts (Java 8 and Java 17 variants), property updaters
├── configuration/ Code style, Checkstyle, formatter configs
├── .github/workflows/ GitHub Actions: Jenkins trigger, SonarCloud
├── AGENTS.md Operational ground truth for AI/human contributors
├── CLAUDE.md Entry point for AI assistants — points to AGENTS.md and docs/
└── EXPANDABLE_BLOCKS_AGENT_INSTRUCTIONS.md Debugging runbook for accordion-style UIs
For the module breakdown in detail, see docs/detailed-design/detailed-design.md §2.
- Java 8 (default branches) or Java 17 (branches whose name contains
java17/java_17). - Maven 3.8.x.
- MySQL 8.x (local instance for development).
- Network access to a CIAT environment if connecting to shared test data:
- Test (CIAT Palmira): FortiClient VPN.
- Staging / Production (AWS): GlobalProtect VPN.
git clone https://github.com/CCAFS/MARLO.git
cd MARLO
git checkout aiccra-staging # branch off here for new workThe properties files holding credentials are gitignored. Bootstrap from the provided template:
cp marlo-web/src/main/resources/config/marlo-test.properties \
marlo-web/src/main/resources/config/marlo-dev.properties
# edit marlo-dev.properties to point at your local MySQL and credentialsActive Spring profile selects which file is loaded: marlo-${spring.profiles.active}.properties. Available profiles: dev, api, pro, test.
Use the run script that matches the branch's Java version:
# Java 8 branches
scripts/run-marlo-java8.sh # macOS / Linux
scripts/run-marlo-java8.bat # Windows
# Java 17 branches (name contains java17 / java_17)
scripts/run-marlo-java17.sh
scripts/run-marlo-java17.batFlyway migrations apply automatically on Tomcat startup. The app comes up on the local Cargo Tomcat instance.
mvn checkstyle:check # mandatory before commit
mvn test # unit testsSonarCloud and Snyk run automatically on push / PR via GitHub Actions.
| Branch | Role | Rules |
|---|---|---|
AICCRA |
Production | Merge-only from aiccra-staging. No direct commits. |
aiccra-staging |
Stable integration | All feature branches merge here. |
aiccra-dev |
Experimentation | Highly unstable; integration testing only. |
aiccra-<slug> |
Feature branches | Created from aiccra-staging; merged back into it. |
CI/CD: a push to any branch triggers the Jenkins job marlo-<branch-suffix>. Slack receives success/failure notifications.
The repository follows a Spec-Driven Development (SDD) methodology. The documents below form the constitutional baseline; module-level work lives under docs/specs/.
AGENTS.md— operational ground truth: language rules, file headers, code style, Checkstyle, migration naming, specificity workflow, file organization, run scripts.CLAUDE.md— entry point for AI assistants; lists the 12 hard rules and the doc-reading order.docs/prd.md— Product Requirements: problem, personas, goals, success metrics, scope, user stories, acceptance, assumptions, open questions.docs/system-design/design.md— UI/UX system blueprint: information architecture, screen inventory, navigation, layout patterns, components, accessibility.docs/detailed-design/detailed-design.md— technical blueprint: modules, data model, phase replication contract, API surface, save pipeline, security, observability, testing, ADR snapshots.
Every module spec under docs/specs/ MUST follow these templates:
docs/specs/general-setup/requirements.mddocs/specs/general-setup/design.mddocs/specs/general-setup/task.md
Spec folders live under:
docs/specs/domain/<module>/— module-level specs (projects, deliverables, innovations, OICRs, POWB, annual report, QA, admin, auth, BI, AI services).docs/specs/enhancement/<feature>/— cross-cutting features.docs/specs/bugfix/<slug>/— bug-driven specs needing structured trace.docs/specs/epic/<name>/— multi-spec initiatives (e.g.,epic/java-17-cutover/,epic/tenant-onboarding/).
The reports/ai-context/ folder holds authoritative operational guides for the most-touched flows:
frontend-composition-map.md— FTL composition (#include,#import, macros, expandable-block templates).save-validation-matrix.md— save pipeline matrix for the 10 critical sections.persistence-replication-managerimpl.md— phase replication contract inManagerImplsave / delete chains.struts-critical-routing-catalog.md— Struts routing catalog with action classes and view results.interceptor-validator-playbook.md— interceptor stacks andAction.validate()patterns.EXPANDABLE_BLOCKS_AGENT_INSTRUCTIONS.md— debugging accordion-style list UIs.
These rules are constitutional. Deviations require an explicit, justified Decision Log entry inside the relevant module spec.
- Phased data is forward-only. Saves replicate to current and future phases; past phases are immutable.
- Save pipeline pattern is mandatory for critical sections:
Action.validate()guarded byif (save)→Validator→ manager save chain. - Spring MVC owns
/api/*. Struts is excluded from this prefix. Do not introduce new*.jsonStruts paths beyond existing patterns. - Specificities (per-Global-Unit feature flags) go through the
parameters+custom_parametersflow, with constants in bothAPConstants.javafiles (marlo-data/andmarlo-web/). - Schema changes ship as Flyway migrations under
marlo-web/src/main/resources/database/migrations/withV<major>_<minor>_<patch>_<YYYYMMDD>_<HHMM>__<Description>.sqlnaming. - GPL header on every new Java file (template in
AGENTS.md). - Code style: 2-space indent, 120 char line limit, braces on same line, mandatory blocks for
if/while/for/do, max file length 3500 lines.mvn checkstyle:checkis a gate. - English only in code, identifiers, and inline comments. User-facing strings MUST be i18n-keyed.
- Branching: never commit directly to
AICCRA. - Run scripts match the branch's Java version (Java 17 only on branches containing
java17/java_17). - Dependency floors (post-January 2026 SETI baseline) MUST NOT be downgraded.
- Never commit credentials.
marlo-${profile}.propertiesis gitignored.
MARLO completed a comprehensive security modernization in January 2026 (executed by SETI). All critical vulnerabilities were remediated and the dependency baseline above was established. Snyk scans run on the monorepo each release cycle. Semi-annual reviews are recommended for legacy components (Pentaho, iText).
To report a security issue, contact the IBD team at Marlosupport@cgiar.org rather than opening a public issue.
- Read
CLAUDE.mdandAGENTS.md. - Branch from
aiccra-stagingasaiccra-<slug>. - Draft the spec under
docs/specs/...(requirements.md→design.md→task.md). - Get the spec reviewed before implementation.
- Implement, keeping
task.mdup to date with verification notes. - Update relevant
reports/ai-context/*.mdfiles when the change alters routing, validation, replication, or composition contracts. - Open a PR into
aiccra-staging. Ensure Checkstyle, SonarCloud, and Snyk are clean.
- MARLO Support:
Marlosupport@cgiar.org - Maintainer: IBD Team — Alliance of Bioversity International and CIAT
- GitHub:
CCAFS/MARLO - Wiki: github.com/CCAFS/MARLO/wiki
- Support tickets are managed through Freshservice; access requests follow the data-governance ticketing process.
MARLO is distributed under the GNU General Public License v3. Every Java source file MUST carry the GPL header documented in AGENTS.md.