This directory contains Architecture Decision Records (ADRs) for the com.cloudempiere.searchindex project.
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
We use the MADR 3.0 format (Markdown Architectural Decision Records). See 000-template.md for the standard template.
| 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) |
| ADR | Title | Status | Date | Description |
|---|---|---|---|---|
| ADR-004 | REST API OData Integration Architecture | 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) |
| 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 |
| 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 |
- 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 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
Phase 1: Quick Performance Fix (1 week)
- ADR-005: Migrate SearchType.POSITION → TS_RANK (100× faster immediately)
- 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
-
Copy template:
cp docs/adr/000-template.md docs/adr/ADR-XXX-short-title.md
-
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?
-
Get review:
- Peer review from team
- Architecture review from tech lead
- Approval from stakeholders
-
Update this index:
- Add new ADR to appropriate category table
- Update ADR relationships diagram if needed
-
Cross-reference:
- Link related ADRs
- Update parent/child ADRs with new relationships
Performance:
- ADR-003: Slovak Text Search Configuration
- ADR-005: SearchType Migration
- ADR-007: Search Technology Selection
Security:
Integration:
- ADR-004: REST API OData Integration (
⚠️ partially superseded by ADR-008) - ADR-008: Search Service Layer (supersedes ADR-004)
Operations:
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
| 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 | 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 |
- Slovak Language Architecture Guide
- Slovak Language Use Cases
- Next Steps Implementation
- LOW-COST-SLOVAK-ECOMMERCE-SEARCH.md
Last Updated: 2026-01-06 Maintainer: Development Team