GOTRS Architecture Review - v0.5.0

Review Summary

Overall Architecture Assessment: EXCELLENT ⭐

GOTRS v0.5.0 represents a significant maturation of the platform, completing the Customer Portal vertical slice and substantially enhancing admin module coverage. The architecture maintains its revolutionary foundations while adding production-critical features.

Key Architectural Achievements

1. Customer Portal Completion

The customer-facing vertical slice is now fully implemented:

Customer Portal Features (v0.5.0)
├── Authentication (JWT with refresh)
├── Ticket Creation (Tiptap rich text)
├── Ticket Viewing (list + detail)
├── Ticket Replies (public/internal)
├── Ticket Closure
├── Service Filtering (customer-user assignment)
├── Default Services (auto-select on create)
├── i18n (EN/DE, 12 templates)
└── Email Threading (RFC-compliant)

Architecture Impact: Clean separation between agent and customer interfaces, shared service layer with customer-specific view rendering.

2. Admin Modules Expansion

3. Self-Registering Handler Architecture

Revolutionary Change: Handlers now register via init() functions:

// Before: Manual registration in main.go
func init() {
    routing.RegisterHandler("/admin/users", HandleAdminUsers)
}

// After: Self-registration via init()
func init() {
    routing.RegisterHandler(&routing.RouteConfig{
        Path:     "/admin/users",
        Handler:  HandleAdminUsers,
        Template: "pages/admin/users.pongo2",
    })
}

Benefits:

• Eliminates manual main.go maintenance
• Test validates all YAML handlers registered (yaml_handler_wiring_test.go)
• Automatic discovery prevents orphaned routes
• Supports dynamic module expansion

4. Email Integration Pipeline

Complete RFC-compliant email threading and connector support:

┌──────────────────────────────────────────┐
│           Email Pipeline                 │
├──────────────────────────────────────────┤
│  Inbound:                                │
│  ├── POP3 Connector (factory pattern)    │
│  ├── IMAP Connector (v2, TLS support)    │
│  ├── Postmaster Processor                │
│  ├── Ticket Token Filters                │
│  └── External Ticket Rules               │
│                                          │
│  Outbound:                               │
│  ├── RFC Threading (Message-ID, refs)    │
│  ├── BuildEmailMessageWithThreading()    │
│  └── GenerateMessageID()                 │
│                                          │
│  Caching:                                │
│  └── Valkey for poll status              │
└──────────────────────────────────────────┘

5. CI/CD Pipeline Overhaul

Complete rewrite of GitHub Actions workflows:

Key Improvements:

• Removed references to non-existent Dockerfile.dev/frontend
• Container-first approach (Go+HTMX monolith)
• OIDC authentication for Codecov
• VCS stamping for coverage reproducibility

6. Dynamic Fields System

7 field types with 52+ unit tests and OTRS-compatible YAML config:

Architecture Evolution

v0.4.0 → v0.5.0 Delta

v0.4.0 Foundation                          v0.5.0 Production
┌─────────────────────┐                   ┌─────────────────────┐
│ • Basic modules     │                   │ • Full admin suite  │
│ • Partial portal    │        →          │ • Complete portal   │
│ • Legacy CI         │                   │ • Container CI      │
│ • Manual handlers   │                   │ • Self-reg handlers │
│ • Basic email       │                   │ • RFC threading     │
└─────────────────────┘                   └─────────────────────┘

Architectural Patterns Strengthened

1. Cross-Database Compatibility

   • ConvertPlaceholders() used consistently
   • InsertWithReturning() for MySQL/PostgreSQL
   • Test parity (Postgres + MySQL containers)

2. Handler Pattern Standardization

   • Dual content-type support (HTMX + JSON)
   • Init-based registration
   • YAML-driven routing consistency

3. Testing Maturity

   • 100+ unit tests added (Services, Dynamic Fields, Templates)
   • YAML handler wiring test
   • Integration fixtures parity

Technology Stack Assessment

Critical Patterns

Database Access Pattern (Enforced)

// All queries use ConvertPlaceholders
rows, err := db.Query(database.ConvertPlaceholders(
    "SELECT * FROM ticket WHERE queue_id = $1", queueID))

// Cross-database INSERT
result, err := database.GetAdapter().InsertWithReturning(
    " INTO sla (name, first_response_time) VALUES ($1, $2) RETURNING id",
    name, firstResponseTime)

Self-Registering Handler

// internal/api/users_init.go
func init() {
    routing.RegisterHandler(&routing.RouteConfig{
        Path:     "/admin/users",
        Method:   "GET",
        Handler:  HandleAdminUsers,
        Template: "pages/admin/users.pongo2",
    })
}

Service Layer Pattern

// Clear separation: Repository → Service → Handler
type TicketService interface {
    Create(ctx context.Context, ticket *Ticket) error
    GetByID(ctx context.Context, id int) (*Ticket, error)
    UpdateStatus(ctx context.Context, id int, statusID int) error
}

Areas for Enhancement

1. Observability (Still Pending)

• Current: Basic logging
• Opportunity: OpenTelemetry integration
• Impact: Production debugging, SLO monitoring

2. Lambda Functions (Unchanged)

• Current: ES5.1 via Goja
• Opportunity: v8go for ES2022+ if CGO acceptable
• Note: Still industry-first, still sandboxed

3. Performance Testing (Gap)

• Current: No documented load tests
• Opportunity: k6 or wrk integration
• Impact: Production capacity planning

4. E2E Test Coverage (Growing)

• Current: Playwright harness exists
• Opportunity: Expand beyond queue preferences
• Note: 29MB gotrs-tests image for test runner

Security Posture

Competitive Position

vs. v0.4.0

• ✅ Complete customer journey
• ✅ Full admin functionality
• ✅ Production-ready CI/CD
• ✅ Comprehensive testing

vs. OTRS/Znuny

• ✅ Modern tech stack (Go vs Perl)
• ✅ Container-native deployment
• ✅ Dynamic modules (zero duplication)
• ✅ Lambda customization (config-driven)
• ✅ HTMX hypermedia (no SPA complexity)

vs. Modern Ticketing (Zendesk, Freshdesk)

• ✅ Self-hosted option
• ✅ Full customization (lambdas)
• ✅ Open-source transparency
• ✅ No per-user pricing model

Recommendations

Immediate (Next 30 Days)

1. Load testing: k6 or wrk for customer portal under load
2. Observability: OpenTelemetry tracing for hot paths
3. Performance profiling: pprof analysis of lambda execution

Medium Term (3-6 Months)

1. Lambda expansion: Add crypto, HTTP utility functions
2. Visual lambda editor: Low-code for business logic
3. E2E pipeline: Expand Playwright beyond queue preferences

Long Term (6-12 Months)

1. Multi-tenant architecture: Leverage dynamic modules
2. AI integration: Lambda-powered extensions
3. 1.0 Release: Production hardening based on field data

Architecture Maturity

Conclusion

GOTRS v0.5.0 achieves production-ready status with:

• Complete customer portal vertical slice
• Comprehensive admin module coverage
• Containerized CI/CD with security scanning
• RFC-compliant email integration
• Self-registering handler architecture

The architecture maintains its revolutionary foundation (dynamic modules, lambda functions) while adding the operational maturity required for production deployment. The separation of concerns (repository → service → handler) and cross-database compatibility patterns provide a solid foundation for enterprise deployment.

Readiness: ✅ Production-ready (subject to organizational readiness factors)

Review conducted: January 3, 2026 Reviewer: Architecture Analysis System Version: GOTRS v0.5.0 Based on: ARCHITECTURE_REVIEW_2025.md (August 2025)