Skip to content

Latest commit

 

History

History
208 lines (153 loc) · 8.9 KB

README.md

File metadata and controls

208 lines (153 loc) · 8.9 KB

Architecture Decision Records (ADRs)

This directory contains Architecture Decision Records (ADRs) for the com.cloudempiere.searchindex project.

What is an ADR?

An Architecture Decision Record (ADR) captures an important architectural decision made along with its context and consequences. ADRs help teams:

  • Understand the reasoning behind architectural choices
  • Avoid revisiting already-made decisions
  • Onboard new team members effectively
  • Track the evolution of the architecture over time

ADR Format

We use the MADR 3.0 format (Markdown Architectural Decision Records). See 000-template.md for the standard template.

ADR Index

Core Search Architecture

ADR Title Status Date Description
ADR-003 Slovak Text Search Configuration Architecture Proposed 2025-12-13 Implements Slovak language support using PostgreSQL text search configuration with multi-weight indexing to replace POSITION workaround
ADR-005 SearchType Migration from POSITION to TS_RANK Proposed 2025-12-12 Migrates default SearchType from POSITION (regex-based, 100× slower) to TS_RANK (native PostgreSQL function)
ADR-007 Search Technology Selection Implemented 2025-12-13 Chose PostgreSQL FTS over Elasticsearch/Algolia (€36,700 cost savings, adequate for 10K-1M products)

API & Integration

ADR Title Status Date Description
ADR-004 REST API OData Integration Architecture ⚠️ Partially Superseded 2025-12-13 Integrates search index with REST API via OData searchindex() filter function (superseded by ADR-008)
ADR-008 Search Service Layer Architecture Proposed 2025-12-18 Service layer with caching, security, and OSGi best practices (supersedes ADR-004)

Security & Data Integrity

ADR Title Status Date Description
ADR-001 Transaction Isolation Implemented 2025-12-12 Ensures proper transaction isolation for search index operations
ADR-002 SQL Injection Prevention Implemented 2025-12-12 Prevents SQL injection in search queries through input sanitization
ADR-006 Multi-Tenant Integrity Proposed 2025-12-12 Fixes unique constraint to include ad_client_id for proper multi-tenant data isolation

Operations & Automation

ADR Title Status Date Description
ADR-010 Automated Search Index Table DDL Management Proposed 2025-12-18 Automates PostgreSQL table creation for new search indexes, eliminating manual DBA intervention (900-3600× faster setup)
ADR-011 Lazy Initialization for SearchIndexEventHandler Accepted 2025-12-29 Fixes startup NullPointerException and chicken-and-egg problem with exponential backoff polling

ADR Status Definitions

  • Proposed: Decision documented but not yet implemented
  • Accepted: Decision approved and ready for implementation
  • Implemented: Decision implemented and deployed to production
  • Deprecated: Decision no longer valid, superseded by newer ADR
  • Superseded: Replaced by a newer ADR (link provided)

ADR Relationships

┌─────────────────────────────────────────────────────────────────┐
│ ADR Dependency Graph                                             │
└─────────────────────────────────────────────────────────────────┘

ADR-007: Technology Selection (PostgreSQL FTS vs Elasticsearch)
    │
    ├─→ ADR-003: Slovak Text Search Configuration
    │       │
    │       └─→ ADR-005: SearchType Migration (POSITION → TS_RANK)
    │               │
    │               ├─→ ADR-004: REST API OData Integration (current)
    │               │       │
    │               │       └─→ ADR-008: Service Layer ← supersedes ADR-004
    │               │               │
    │               │               ├─→ ADR-001: Transaction Isolation
    │               │               └─→ ADR-002: SQL Injection Prevention
    │               │
    │               └─→ ADR-001: Transaction Isolation
    │
    ├─→ ADR-006: Multi-Tenant Integrity
    │       │
    │       └─→ ADR-010: Automated Table DDL ← ensures ADR-006 schema
    │
    └─→ ADR-010: Automated Table DDL Management

Legend:
─→ depends on / related to / evolves to

Critical Path for Implementation

Phase 1: Quick Performance Fix (1 week)

  1. ADR-005: Migrate SearchType.POSITION → TS_RANK (100× faster immediately)
  2. ADR-004: Update REST API to use TS_RANK (fix both query converters)

Phase 2: Slovak Language Support (2 weeks) 3. ADR-003: Implement Slovak text search configuration 4. ADR-005: Complete migration with multi-weight indexing

Phase 3: Data Integrity (1 week) 5. ADR-006: Fix multi-tenant unique constraint

Creating a New ADR

  1. Copy template:

    cp docs/adr/000-template.md docs/adr/ADR-XXX-short-title.md

  2. Fill in all sections:

    • Context: What problem are we solving?
    • Decision Drivers: What factors influence the decision?
    • Considered Options: What alternatives did we evaluate?
    • Decision: What did we choose and why?
    • Consequences: What are the positive/negative/neutral outcomes?

  3. Get review:

    • Peer review from team
    • Architecture review from tech lead
    • Approval from stakeholders

  4. Update this index:

    • Add new ADR to appropriate category table
    • Update ADR relationships diagram if needed

  5. Cross-reference:

    • Link related ADRs
    • Update parent/child ADRs with new relationships

Quick Reference

By Topic

Performance:

Security:

Integration:

Operations:

By Status

Implemented/Accepted:

  • ADR-001, ADR-002, ADR-007, ADR-011
  • ADR-004 (⚠️ partially superseded by ADR-008)

Proposed (Ready for Implementation):

  • ADR-003, ADR-005, ADR-006, ADR-008, ADR-009, ADR-010

Deprecated:

  • None

Implementation Tracking

ADR Implementation Status Blocker Target Date
ADR-003 Not Started Requires database migration script Q1 2026
ADR-005 ✅ UI Done, REST Open REST API in cloudempiere-rest repo Q1 2026
ADR-004 ⚠️ Implemented with gaps Superseded by ADR-008 Q1 2026
ADR-006 Not Started Requires schema migration Q2 2026
ADR-008 Not Started None (ready to implement) Q1 2026
ADR-009 Not Started None (ready to implement) Q2 2026
ADR-010 Not Started None (ready to implement) Q1 2026
ADR-011 ✅ Done Released in v10.1.0 Done

Additional Resources

Implementation Guides

External References

Last Updated: 2026-01-06 Maintainer: Development Team