Skip to content
MarreqSWPublic

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

2,532 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Requirement Manager (Marreq)

Codacy Badge

A comprehensive web-based requirements and test management system built with Rust, Rocket, and PostgreSQL. The primary UI is a React 19 + Vite + TypeScript SPA (Tailwind CSS; React Flow for traceability), talking to a JSON API under /api. Legacy client assets remain under frontend/static/ for gradual migration (@static in Vite). This software supports hierarchical requirements, tests (verifications), traceability matrices, baselines, reports, and exports.

Documentation index (by audience): docs/README.md

Installation (operations): host packages, Docker, database, CI parity β€” see INSTALL.md.

✨ Features

πŸ“‹ Core Management

  • Multi-Project Support: Manage multiple projects with isolated data
  • Requirements Management: Create, edit, and organize hierarchical requirements
  • Test Management: Manage tests with status tracking and source documentation
  • Traceability Matrix: Visual mapping between requirements and tests; requirement detail page lists all linked tests per requirement (β€œVerified by” section with links to test pages)
  • Attachments: Files on requirements and verifications (PDF, images, Office/OpenDocument, ZIP, text/CSV/JSON/XML; checked against the file's bytes, always served as downloads). Stored once per content hash on disk, with a per-file limit and a per-project storage quota that instance admins can override (MARREQ_ATTACHMENTS_DIR, MARREQ_ATTACHMENT_MAX_MB default 10, MARREQ_PROJECT_STORAGE_QUOTA_MB default 500). Baselines keep the files they recorded
  • User Management: Assign authors and reviewers to requirements with authentication
  • Project reviewers: Per-project list of members who may change requirement status, verification status, and version approval (draft / reviewed / approved); configured in the SPA Settings or via GET/PUT /api/projects/<id>/reviewers

🏷️ Advanced Features

  • Requirement comments: Comment threads on requirements and optional requirement versions; author, timestamp, optional version reference; chronological list; immutable after creation. UI panel on requirement/version detail pages; approved versions can be locked from new comments (LOCK_APPROVED_VERSION_COMMENTS). Comments in audit logs and in Excel/ReqIF exports.
  • Requirement version diff: Compare two requirement versions or a baseline snapshot vs current; API returns structured diff (metadata, verification, text) with optional labels (e.g. Status β€œDraft”, verification method titles) in addition to IDs; UI diff modal shows these labels for easier reading
  • Verification snapshot diff: Compare two verification snapshots reconstructed from the audit log; SPA dialog on view/edit pages
  • Categories: User-defined categories for organizing requirements (project-specific)
  • Applicability: Define product lines, system types, or project scopes (project-specific)
  • Status Tracking: Track requirement status (Draft, Accepted, Rejected, etc.)
  • Verification Methods: Specify verification types (Test, Analysis, Review, etc.)
  • Authentication: Password plus federated Google/GitHub/GitLab login in Cloud and configurable OIDC SSO in Server; see authentication configuration
  • Project Isolation: Data separation between different projects

πŸ“Š Reporting & Export

  • Excel Export: Export requirements with all fields to Excel format; includes a Comments sheet (requirement_id, version_id, author, created_at, body)
  • Matrix Export: Export traceability matrix to Excel
  • ReqIF 1.2 (partial): Backend import/export with hierarchy and representable relations; ReqIFZ archives carry attachment files both ways (MARREQ_REQIFZ_MAX_MB, default 100); custom datatypes, rich XHTML and lossless vendor round-trips remain limited. See the compatibility report
  • Comprehensive Data: All metadata included in exports (categories, applicability, dates, comments, etc.)

πŸ“Έ Immutable Baselines

  • Project Baselines: Create point-in-time snapshots of all requirement versions and traceability
  • Immutable: Baselines and their contents cannot be updated or deleted (enforced at DB and API level)
  • Version Snapshot: Each baseline stores which requirement_version was current per requirement, plus the traceability matrix at creation time
  • Export from Baseline: ReqIF and UI support exporting a specific baseline for audits or releases
  • API & UI: Create/list/view baselines via REST API and web UI (project Baselines section, nav, requirements export dropdown)
  • Baseline detail page: View baseline metadata, requirements table, and full traceability list; requirement and test references (e.g. REQ-PWR-001, TEST-PWR-001) are shown instead of raw IDs, with one row per (requirement, test) link
  • Diff vs current: From a baseline view, compare a requirement’s snapshot to the current version in a diff modal; the β€œDiff vs current” action is hidden when the requirement is unchanged (same version as current)

🎨 Web UI (React SPA)

  • Stack: React 19, Vite 6, TypeScript, Tailwind CSS; light/dark theming and shared design tokens
  • Routing: Login, project-scoped requirements and verification views, requirement editor, traceability graph β€” see frontend/README.md
  • Responsive: Layout tuned for desktop and smaller viewports
  • Same-origin API: Session cookies and CSRF work when the SPA and /api share an origin (Docker nginx or Vite dev proxy); details in docs/developer/http-api-contract.md

πŸ”Œ API Access

  • RESTful API: Complete programmatic access to all data
  • JSON Format: Standard JSON responses for integration
  • CRUD Operations: Full Create, Read, Update, Delete support
  • Project-Scoped: All API operations respect project boundaries; project-scoped routes support both session and Bearer token auth (e.g. for MCP)
  • API tokens: Bearer token auth for headless clients (e.g. MCP); tokens can be scoped to a project (see MCP Setup)

πŸ€– MCP (Model Context Protocol)

  • MCP server: Optional TypeScript MCP server in mcp-server/ that exposes a subset of the REST API as MCP tools for AI assistants (Cursor, Claude, etc.). Bearer token; project-scoped. Full parity matrix: MCP Setup.
  • Remote access: Streamable HTTP at configurable /mcp, with Marreq-issued delegated OAuth credentials, explicit capability consent, and connected-application revocation. Local stdio + API-token use remains supported.
  • Core read (default): MARREQ_MODE=read_only β€” requirements, trace, coverage, baselines (get + diff).
  • Extended read: MARREQ_MODE=read_extended (or draft_write) β€” verifications, baseline list, audit activity, comments, matrix read, catalog, baseline-vs-current diff.
  • Draft write: MARREQ_MODE=draft_write β€” create/patch requirement, approvals, baselines, requirement comments.
  • Trace write: MARREQ_TRACE_WRITE=true β€” replace verification matrix links, clear suspect flags.
  • Audit: Tool calls emit trusted, best-effort audit events through an internally authenticated endpoint; audit transport failure never changes a committed tool result into a retryable failure.

βœ… Requirement approval workflow (UI)

  • Detail page: Approval badge (draft / reviewed / approved), metadata (approved by, date), and contextual actions: Mark as Reviewed and Approve Requirement for users in the project reviewers list (or administrators). Confirmation modals before each transition.
  • Edit when approved: Clicking Edit on an approved requirement shows a warning that editing creates a new Draft version; user can cancel or proceed.
  • Version history: Each version shows its approval state; list and detail show approval consistently.
  • List view: Approval column and filters (Approved only / Not approved). Approval state is read-only once set; transitions are explicit and audit-friendly.

ToDo List

  • Hierarchy for
    • Requirements
    • Tests
  • Better webpage
    • Use templates (based on hbs)
    • Modern CSS design system
    • Responsive layout
  • Reports generator
    • Excel export for requirements
    • Excel export for traceability matrix
    • Latex template
    • PDF document
  • Categories management
    • CRUD operations
    • API endpoints
  • Applicability management
    • CRUD operations
    • API endpoints
  • REST API (comprehensive)
    • Requirements endpoints
    • Tests endpoints
    • Categories endpoints
    • Applicability endpoints
    • Matrix endpoints
  • Operations logging
  • Parsers for requirements
    • Latex files (Write a command)
    • Word files (Write a macro)
    • Excel files
  • Parsers for tests
    • Doxygen documentation
    • ...
  • Multiple projects
  • Optimize DB access
    • Reduce SQL queries
    • DB pool
  • Security
    • Use https
    • users/admin
  • Snapshots
    • Immutable project baselines (requirement versions + traceability)
    • Configuration management
  • Better error management
    • Remove unwrap/expect in production paths (guards, routes, DB init, Excel export)
    • Result-based DB pool init; clear startup failure message
    • try_repo_read/try_repo_write for non-panicking lock in request path

πŸš€ Quick Start

Prerequisites

  • PostgreSQL: Database backend (provided via Docker)
  • Docker & Docker Compose: For database containerization
  • Rust: Programming language
  • C toolchain, pkg-config, libssl-dev and libpq-dev: For the native crates (OpenSSL, libpq, aws-lc)

Installation

Quick Start (Recommended)

For a fully initialized database with pre-configured users and sample data, use the helper scripts described in the scripts README, in particular db_setup.sh (optionally followed by db_seed.sh).

Typical flow:

  • Start database: docker compose -f docker/docker-compose.yml up -d db
  • Initialize DB schema: ./marreq-core/scripts/db_setup.sh
  • Load sample data (optional): ./marreq-core/scripts/db_seed.sh
  • Start API (self-hosted mode): cargo run -p marreq-server β€” serves http://127.0.0.1:8000 with JSON under /api.

For the full browser UI locally, run the SPA against that API:

cd frontend
npm install
npm run dev   # http://localhost:5173 β€” proxies /api β†’ http://127.0.0.1:8000

Demo admin user alice / ChangeMe123! (change after first login).

For the full setup matrix (marreq-server vs marreq-cloud, Docker vs local), see the setup guide. For database-only details (automated, manual, reset, verification), see the database setup guide.

Docker: API backend + SPA frontend

The default docker/docker-compose.yml stack runs db, marreq-server (Rocket JSON API on 127.0.0.1:8000), frontend (nginx serving the production Vite build on http://localhost:8080 with /api/ proxied to marreq-server), and adminer (http://localhost:8081). The cloud compose profile adds marreq-cloud on 127.0.0.1:8001 plus frontend-cloud on http://localhost:8082. See the setup guide, docker/README.md, and the HTTP API contract.

Workspace layout, deployment modes, and build commands: docs/developer/workspace-layout.md. SPA scripts, routes, and API mapping: frontend/README.md.

πŸ“– Usage

Web interface

Use the SPA (Docker http://localhost:8080 or npm run dev in frontend/). Sign in, pick a project, then use requirements, verifications, traceability, and related flows from the in-app navigation.

  1. Requirements: View and manage requirements (versions, comments where exposed in the UI). Comments on requirement/version views follow project rules (e.g. locked on approved versions when configured).
  2. Verifications (tests): Manage verification records per project
  3. Traceability: Matrix / graph views linking requirements and verifications
  4. Baselines: Create and inspect immutable snapshots; export ReqIF where the UI exposes it; diff vs current when available
  5. Categories & applicability: Managed per project where the UI provides entry points (additional admin flows may be API-only)

Export Features

  • Requirements Export: Click "Export Excel" on the requirements page or homepage
  • Matrix Export: Click "Export Excel" on the matrix page
  • ReqIF Export: On Reports, download Requirements (.reqif) or Requirements with files (.reqifz) for the live project, or open a baseline and use Export ReqIF / Export ReqIFZ (with files) for that snapshot.
  • File Format: Excel downloads as .xlsx; ReqIF as XML (.reqif), or as a ZIP archive with the attachment files (.reqifz)

Import Features

  • Excel Import (Web UI): Open Import in a project (/{slug}/import), upload .xlsx/.csv, map columns, then create requirements or verifications
  • ReqIF 1.2 Import (Web UI): Same Import page; upload .reqif/.xml, or a .reqifz archive whose referenced files become attachments. Catalog defaults are applied on the server; warnings are shown after import.
  • Indexing integration: Imported requirements are queued for semantic index refresh when embeddings are enabled

πŸ”Œ API Reference

Interchangeable clients: session auth, CSRF, and Docker/nginx notes are documented in docs/developer/http-api-contract.md. A partial OpenAPI spec covers auth and session-scoped project listing.

Base URL

http://localhost:8000/api

Behind the Docker frontend (or Vite dev), use the same origin as the SPA (e.g. http://localhost:8080/api/...). JSON routes are mounted under /api from marreq-core/src/api/mod.rs (shared routes) and the deployment crate's src/routes.rs (deployment-specific routes). When adding or changing API endpoints, update this section so the list stays in sync.

Endpoints

Auth & session (JSON / SPA)

  • GET /auth/csrf β€” JSON { "csrf_token" } for mutating requests (X-CSRF-Token header)
  • POST /auth/login β€” JSON body username, password; sets session + CSRF cookies
  • POST /auth/logout β€” clears session
  • GET /auth/me β€” current user or 401 JSON (not HTML login page)
  • GET /projects β€” projects for logged-in user (admin: all; others: memberships)
  • GET /project-from-path/{slug} β€” resolve /{slug} to project id (SPA deep links; 403 if not a member)
  • GET /projects/{project_id}/verifications β€” list verifications (tests) in the project (ViewRequirements)

Projects

  • GET /projects - Projects visible to the current user
  • POST /projects - Create a project (body: name, optional description, group_id)
  • PATCH /projects/{project_id} - Edit name, description, status, owner or group (project Admin or instance admin; the slug is fixed)
  • DELETE /projects/{project_id} - Permanently delete the project and all its data (owner or instance admin; body confirm_slug; session only)

Requirements

  • GET /requirements - List all requirements
  • GET /requirements/{id} - Get specific requirement
  • GET /requirements/{id}/versions - List versions for a requirement (newest first)
  • GET /requirements/{req_id}/versions/{version_id} - Get a specific requirement version (includes custom fields and verification method ids)
  • GET /requirements/{req_id}/versions/{v1}/diff/{v2} - Diff two requirement versions (structured JSON: text and metadata added/removed/unchanged; includes optional labels for status, category, applicability, verification)
  • PUT /requirements/{req_id}/versions/{version_id}/approval - Set approval state (body: state: "reviewed" | "approved"; project owners/managers only)
  • GET /requirements/{id}/comments - List comments for a requirement (query: optional version_id; chronological order)
  • POST /requirements/{id}/comments - Add a comment (body: body, optional requirement_version_id; approved versions rejected when LOCK_APPROVED_VERSION_COMMENTS=true)
  • POST /requirements - Create new requirement
  • POST /projects/{project_id}/imports/excel/preview - Parse Excel/CSV and return columns for mapping (EditRequirements)
  • POST /projects/{project_id}/imports/excel - Import mapped Excel/CSV as requirements or verifications
  • PATCH /requirements/{id} - Partially update supported requirement fields
  • DELETE /requirements/{id} - Delete requirement

Project-scoped (session or Bearer token):

  • GET /projects/{project_id}/requirements - List requirements; query: approval_state, has_tests
  • GET /projects/{project_id}/requirements/{id} - Get requirement with trace summary (parent, children, linked tests)
  • GET /projects/{project_id}/requirements/{id}/versions - List versions (newest first)
  • GET /projects/{project_id}/requirements/{req_id}/versions/{version_id} - Get a version snapshot (includes custom fields and verification method ids)
  • GET /projects/{project_id}/requirements/{req_id}/versions/{v1}/diff/{v2} - Diff two versions (requirement must belong to project)
  • POST /projects/{project_id}/requirements - Create requirement (body must include project_id matching route)
  • PATCH /projects/{project_id}/requirements/{id} - Partially update requirement
  • PUT /projects/{project_id}/requirements/{req_id}/versions/{version_id}/approval - Set approval state (body: state: "reviewed" | "approved")

Tests

  • GET /tests - List all tests
  • GET /tests/{id} - Get specific test
  • POST /tests - Create new test
  • POST /tests/{id}/field - Partially update a test field (body: field, value; supported fields: name, description, source, status_id, reference_code, parent_id)
  • DELETE /tests/{id} - Delete test

Categories

  • GET /categories - List all categories
  • GET /categories/{id} - Get specific category
  • POST /categories - Create new category
  • PUT /categories/{id} - Update category
  • DELETE /categories/{id} - Delete category

Applicability

  • GET /applicability - List all applicability options
  • GET /applicability/{id} - Get specific applicability
  • POST /applicability - Create new applicability
  • PUT /applicability/{id} - Update applicability
  • DELETE /applicability/{id} - Delete applicability

Matrix

  • GET /matrix - Get traceability matrix data
  • GET /projects/{project_id}/matrix - Get traceability matrix for a project (session or Bearer)

Attachments & storage

  • GET /projects/{project_id}/attachments?entity_type=requirement|verification&entity_id= - List attachments of a requirement or verification
  • POST /projects/{project_id}/attachments - Upload (multipart file, entity_type, entity_id); 413 over the size limit or quota, 415 for disallowed types
  • GET /projects/{project_id}/attachments/{attachment_id}/download - Download (always Content-Disposition: attachment)
  • DELETE /projects/{project_id}/attachments/{attachment_id} - Delete (files kept by baselines stay available there)
  • GET /projects/{project_id}/storage - Storage used, quota and upload limits
  • PUT /projects/{project_id}/storage/quota - Set ({"quota_mb": n}) or reset (null) the project quota; instance admins only
  • GET /projects/{project_id}/baselines/{baseline_id}/attachments (+ /{attachment_id}/download) - Files recorded in a baseline

Baselines (immutable snapshots)

  • GET /projects/{project_id}/baselines - List baselines for a project
  • GET /projects/{project_id}/baselines/{baseline_id} - Get baseline metadata
  • POST /projects/{project_id}/baselines - Create baseline (body: name, description; captures current requirement versions and traceability)
  • GET /projects/{project_id}/baselines/{baseline_id}/requirements - Get requirements as stored in the baseline
  • GET /projects/{project_id}/baselines/{baseline_id}/requirements/{req_id}/diff/current - Diff requirement in baseline vs current version (structured JSON with optional labels for status, category, applicability, verification)
  • GET /projects/{project_id}/baselines/{baseline_id}/traceability - Get traceability snapshot for the baseline

Users

  • GET /users - List all users
  • GET /users/{id} - Get specific user
  • POST /users - Create new user
  • DELETE /users/{id} - Delete user

Status

  • GET /status - List all status options
  • GET /status/{id} - Get specific status
  • POST /status - Create new status

Traceability

  • GET /projects/{project_id}/requirements/{id}/trace_up - Get parent requirement(s) (session or Bearer)
  • GET /projects/{project_id}/requirements/{id}/trace_down - Get child requirements and linked tests (session or Bearer)
  • GET /projects/{project_id}/coverage_report - Requirements without tests, tests without requirements, suspect links (session or Bearer)
  • GET|PUT /projects/{project_id}/verifications/{id}/control - Verification level, stage and evidence reference (issue #353)
  • GET /projects/{project_id}/requirements/{id}/close_out, GET /projects/{project_id}/close_out - Compliance assessment and derived close-out (open/closed with a reason)
  • PUT /projects/{project_id}/requirements/{id}/compliance - Set C / PC / NC or clear it (project reviewers)
  • GET /projects/{project_id}/reports/types - Report document types (VCD, traceability & coverage), their sections and default templates
  • GET|POST /projects/{project_id}/report_templates, GET|PATCH|DELETE /projects/{project_id}/report_templates/{id} - Saved report templates (section order, on/off, options, document fields)
  • POST /projects/{project_id}/reports/{vcd|coverage}.{pdf|odt} - Generate a report document (body: optional template_id or definition)
  • GET /projects/{project_id}/dsm - Dependency structure matrix: requirement Γ— requirement links, loops and upstream changes (query: link_types, order=hierarchy|partition, category_id, root_id; session or Bearer)
  • GET /projects/{project_id}/exports/dsm.xlsx - The same matrix as an Excel workbook (DSM, Loops and Legend sheets)
  • POST /traceability/clear_suspect - Clear suspect flag for a traceability link (body: req_id, test_id; records current user and timestamp)

Semantic search (project-scoped; requires embeddings/RAG when enabled)

  • GET /projects/{project_id}/requirements/semantic_search - Search requirements by semantic similarity (query params: q, optional k, filters)
  • POST /projects/{project_id}/requirements/ask - RAG answer over project requirements (body: query, optional k, filters)
  • POST /projects/{project_id}/requirements/reindex - Reindex all requirements for the project (admin only)
  • GET /projects/{project_id}/requirements/index_status - Get indexing status for the project
  • GET /projects/{project_id}/requirements/semantic_search/status - Check if semantic search is enabled

Cache (internal/operational)

  • GET /cache/stats - Cache statistics
  • POST /cache/clear - Clear cache
  • POST /cache/cleanup - Remove expired entries
  • GET /cache/performance - Cache performance metrics
  • GET /cache/recommendations - Cache tuning recommendations
  • POST /cache/reset-counters - Reset performance counters
  • GET /cache/health - Cache health check

Example API Usage

# Get all requirements
curl http://localhost:8000/api/requirements

# Create a new category
curl -X POST http://localhost:8000/api/categories \
  -H "Content-Type: application/json" \
  -d '{"title": "API", "description": "API requirements", "tag": "API"}'

# Export requirements to Excel
curl -O http://localhost:8000/requirements.xls

πŸ—„οΈ Database

Schema

The application uses PostgreSQL with the following main entities:

  • Projects: Multi-project support with project metadata
  • Requirements: Logical requirement containers; current content lives in requirement_versions (immutable version history)
  • Requirement versions: Immutable snapshots of requirement content (title, description, status, category, applicability, etc.)
  • Requirement comments: Immutable comments attached to a requirement (general) or a specific version; author, body, created_at; optional requirement_version_id
  • Tests: Test cases with status and source information, project association
  • Matrix: Traceability links between requirements and tests (live), project-scoped
  • Baselines: Immutable project snapshots; baseline_requirements stores which requirement_version was current per requirement, baseline_traceability stores the matrix at baseline time
  • Categories, Applicability, Requirement status, Test status, Verification: Project-scoped lookup/config tables
  • Users: System users (authors, reviewers) with authentication
  • User API tokens: Bearer tokens for headless/MCP access; optional project scope; hashed storage, last_used_at tracking
  • Logs: Audit trail for all system activities

For a full entity-relationship diagram see docs/architecture/database-schema.md (Mermaid).

Database Initialization System

A comprehensive database initialization system is provided, including SQL files, helper scripts, pre-configured users, and rich sample data.

  • For end-to-end database setup and reset via scripts, see the scripts README (db_setup.sh, db_seed.sh, db_reset.sh).
  • For a full description of the schema, sample projects/users, and manual initialization commands, see the database setup guide.

Migrations

Database schema changes are managed through Diesel migrations (diesel.toml lives in marreq-core/; run CLI commands from there):

cd marreq-core

# Create new migration
diesel migration generate migration_name

# Run migrations
diesel migration run

# Revert migrations
diesel migration redo

Note: Migrations are the single source of truth for schema creation/evolution. marreq-core/scripts/init_complete.sql is seed data only (sample projects/users/requirements) and should be run after migrations.

πŸ› οΈ Development

Project structure

Marreq/
β”œβ”€β”€ Cargo.toml              # Virtual workspace (marreq-core, marreq-server, marreq-cloud)
β”œβ”€β”€ Cargo.lock              # Single lock-file for the whole workspace
β”œβ”€β”€ Makefile                # make server / make cloud / make test / …
β”œβ”€β”€ marreq-core/            # shared lib (domain, persistence, Rocket primitives)
β”‚   β”œβ”€β”€ Cargo.toml
β”‚   β”œβ”€β”€ src/                # Library source (api/, auth/, services/, models/, …)
β”‚   β”œβ”€β”€ migrations/         # Diesel migrations (schema source of truth)
β”‚   β”œβ”€β”€ diesel.toml
β”‚   └── scripts/            # Dev tooling & DB helpers
β”‚       β”œβ”€β”€ db_setup.sh
β”‚       β”œβ”€β”€ db_seed.sh
β”‚       β”œβ”€β”€ db_migrate.sh
β”‚       β”œβ”€β”€ db_reset.sh
β”‚       β”œβ”€β”€ db_backup.sh
β”‚       β”œβ”€β”€ run_checks.sh   # fmt, clippy, stylelint, purgecss, npm test
β”‚       β”œβ”€β”€ run_tests.sh
β”‚       └── init_complete.sql
β”œβ”€β”€ marreq-server/          # self-hosted binary (admin-managed users)
β”‚   β”œβ”€β”€ Cargo.toml
β”‚   └── src/
β”‚       β”œβ”€β”€ main.rs         # Rocket launch for server mode
β”‚       β”œβ”€β”€ deployment.rs   # impl DeploymentMode for Server
β”‚       β”œβ”€β”€ api/            # Server-only REST handlers
β”‚       └── routes.rs       # pub fn routes() for server-only routes
β”œβ”€β”€ marreq-cloud/           # hosted/SaaS binary (self-registration)
β”‚   β”œβ”€β”€ Cargo.toml
β”‚   └── src/
β”‚       β”œβ”€β”€ main.rs         # Rocket launch for cloud mode
β”‚       β”œβ”€β”€ deployment.rs   # impl DeploymentMode for Cloud
β”‚       β”œβ”€β”€ api/            # Cloud-only REST handlers (register, verify-email, …)
β”‚       β”œβ”€β”€ services/       # registration_service.rs
β”‚       β”œβ”€β”€ fairings/       # cloud_admin_bootstrap.rs
β”‚       └── routes.rs       # pub fn routes() for cloud-only routes
β”œβ”€β”€ frontend/               # React + Vite SPA + legacy static/
β”‚   β”œβ”€β”€ src/                # React app (main.tsx, routes, components)
β”‚   β”œβ”€β”€ static/             # Legacy JS/CSS (optional @static alias)
β”‚   └── package.json
β”œβ”€β”€ docs/                   # Documentation (developers/architects/users)
β”‚   β”œβ”€β”€ README.md           # Documentation index
β”‚   └── ReqIF/              # ReqIF standards and reference docs
β”œβ”€β”€ mcp-server/             # Optional MCP server (Node/TypeScript) for AI assistants
β”œβ”€β”€ docker/                 # Container files (compose, Dockerfile, entrypoint, CI override)
β”‚   β”œβ”€β”€ docker-compose.yml  # Main Docker Compose stack
β”‚   β”œβ”€β”€ docker-compose.ci.yml
β”‚   β”œβ”€β”€ Dockerfile          # Backend image (MARREQ_BIN=marreq-server|marreq-cloud)
β”‚   β”œβ”€β”€ frontend/           # Frontend image + nginx config
β”‚   β”œβ”€β”€ docker-entrypoint.sh
β”‚   └── README.md

Key technologies

  • Backend: Rust, Rocket, Diesel, PostgreSQL
  • Frontend: React 19, TypeScript, Vite, Tailwind CSS (see frontend/README.md)
  • Legacy assets: frontend/static/ (not loaded by default in the React shell)
  • Reports: Excel generation with rust_xlsxwriter (pure Rust)
  • Containerization: Docker Compose (db, backend, frontend, optional services)

Building

# Development build (all crates)
cargo build --workspace

# Release build
cargo build --workspace --release

# Run tests (all crates)
cargo test --workspace

# Run tests for a specific crate
cargo test -p marreq-core

# Integration tests live in one binary per crate (`tests/it/`, one module per
# area); add new files there as `mod` entries in `tests/it/main.rs`.
# Run a single area:
cargo test -p marreq-core --test it api_users

# Run all checks (fmt, clippy, stylelint, purgecss, npm ci, npm test)
bash marreq-core/scripts/run_checks.sh

# Run backend test suite with summary output
bash marreq-core/scripts/run_tests.sh

# Run local CI flow (supports --jobs)
bash marreq-core/scripts/run_ci.sh local-ci --jobs 2

πŸ“ License

This project is open source. See LICENSE file for details.

🀝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

πŸ”§ Troubleshooting

Common Issues

Application Startup Issues

If the app exits immediately with "Database setup failed", set DATABASE_URL (e.g. in .env) and ensure the database is reachable. The app uses Result-based pool initialization and will not start without a valid pool.

# Check if port 8000 is in use
lsof -i :8000

# Kill existing process
kill <PID>

# Start application (self-hosted mode)
cargo run -p marreq-server

Login Issues

  • Default credentials: Seeded admin alice has password ChangeMe123! (change after first login).
  • Available users: alice, dr_smith, eng_jones, tech_lee, qa_wilson, admin
  • Reset passwords: Update database directly or re-run setup script

Performance Issues

  • Database indexes: The initialization script includes optimized indexes
  • Connection pooling: Application uses connection pooling for better performance
  • Query optimization: Consider adding indexes for custom queries

πŸ“ž Support

For issues and questions, please open an issue on the project repository.

Getting Help

  1. Check troubleshooting section above
  2. Review application logs for error messages
  3. Run Docker checks/reset from docker/README.md
  4. Check Docker container status
  5. Open an issue with detailed error information

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages