Architecture Diagrams

Key Components:

• Client Layer: Web, Desktop (Tauri), Android, iOS, and API clients
• Core API Layer: Unified /do endpoint with 282 actions
• Middleware: JWT validation, CORS, logging, rate limiting, WebSocket support
• Handlers: V1 (144 actions), Phase 1 (45 actions), Phase 2 (62 actions), Phase 3 (31 actions)
• Database Layer: SQLite/PostgreSQL abstraction with V3 schema (89 tables)
• Monitoring Layer: Structured logging, health checks, metrics, audit trail

Schema Domains:

• Core Domain (V1): 61 tables - Projects, Tickets, Comments, Workflows, Boards, Cycles, Multi-tenancy
• Phase 1 - JIRA Parity: +11 tables - Priorities, Resolutions, Versions, Watchers, Filters, Custom Fields
• Phase 2 - Agile Enhancements: +15 tables - Epics, Subtasks, Work Logs, Project Roles, Security Levels, Dashboards
• Phase 3 - Collaboration: +2 tables - Voting System, Project Categories, Comment Mentions
• Mapping Tables: 40+ many-to-many relationship tables and metadata extensions

Design Patterns:

• UUID for all IDs (globally unique identifiers)
• Soft deletes (deleted column for data retention)
• Audit timestamps (created, modified for tracking)
• Hierarchical permissions (context-based access control)
• JSON for flexible configuration storage
• Denormalized vote_count for performance optimization

Request Flow Steps:

• 1. Client Request: POST /do with action, JWT, object, and data payload
• 2. Gin Router: Parse JSON, validate format, extract action parameter
• 3. Middleware Stack: JWT validation, CORS handling, request logging, metrics tracking
• 4. Handler Router: Switch on action (282 total actions available)
• 5. Permission Check: Via Permissions Engine using RBAC model
• 6. Business Logic: Execute action handler (e.g., handlePriorityCreate())
• 7. Database Layer: Execute SQL via abstraction (SQLite/PostgreSQL)
• 8. Response Builder: Build success/error response with standardized format
• 9. Client Response: HTTP 200 OK with JSON response or appropriate error

Error Handling:

• 1000 series: Invalid Request, Missing Parameters
• 1002/1003: Missing/Invalid JWT Token
• 1009: Permission Denied (insufficient privileges)
• 2001: Database Error (connection, query failures)
• 3000: Entity Not Found (resource doesn't exist)
• 3002: Validation Failed (invalid data format)

Authentication Flow (JWT):

• 1. Login Request: POST /do with username/password credentials
• 2. Core → Auth Service: Validate credentials (if service enabled) or local auth
• 3. Generate JWT Token: Include claims (username, role, permissions, expiration)
• 4. Return Token: Client receives token for subsequent authenticated requests

JWT Payload Structure:

• sub: "authentication" (subject identifier)
• username: User's unique username
• name: User's full display name
• role: admin | user | viewer | guest
• permissions: READ | CREATE | UPDATE | DELETE | ALL
• exp: Token expiration timestamp

Authorization Flow (RBAC):

• 1. Request with JWT: POST /do with action, jwt, object, data
• 2. JWT Validation: Parse, verify signature, check expiration, extract claims
• 3. Permission Check: permService.CheckPermission(username, object, action)
• 4. Result: ALLOWED ✓ (proceed) or DENIED ✗ (error 1009)

Permissions Engine:

• Roles: admin (ALL), user (READ/CREATE/UPDATE), viewer (READ), guest (limited READ)
• Permission Values: READ (1), CREATE (2), UPDATE (3), DELETE/ALL (5)
• Contexts: Hierarchical - node → account → organization → team/project
• Security Levels: Confidential, Internal, Public (project-level)
• Project Roles: Administrator, Developer, Reporter, Viewer

Core Service (HelixTrack Core):

• Technology: Go 1.22+ / Gin Gonic web framework
• Port: 8080 (configurable via JSON config)
• Protocol: HTTP/HTTPS with TLS/SSL support
• Database: SQLite (development) / PostgreSQL (production)
• Features: 282 API Actions across V1, Phase 1, Phase 2, Phase 3
• Schema: V3 (89 tables with full JIRA parity)
• Performance: 50K+ requests/second with <5ms response time

Mandatory Services:

• Authentication Service (Port 8081): JWT token validation, endpoints: /authenticate, /validate, /refresh (can be disabled for testing)
• Permissions Engine (Port 8082): RBAC permission checks, endpoints: /check, /permissions/:user, /grant (can be disabled for testing)

Optional Extensions:

• Lokalisation (Port 8083): i18n/l10n multi-language support with translation management
• Times (Port 8084): Time tracking, timesheets, time reports, work log analysis
• Documents (Port 8085): Document management, file storage, versioning, metadata
• Chats (Port 8086): Real-time chat with Slack, Telegram, WhatsApp integrations, rooms, mentions, presence

HTTP Communication:

• JSON over HTTP/HTTPS with RESTful conventions
• Timeout: 30 seconds (configurable per service)
• Retry: 3 attempts with exponential backoff
• Circuit breaker pattern for fault tolerance
• Connection pooling for performance optimization
• TLS/SSL support for encrypted communication

Deployment Scenarios:

• Development (Single Machine): All services on localhost with different ports
• Production (Distributed): Services on different machines/clusters with load balancing
• High Availability: Kubernetes/Docker Swarm with auto-scaling, service mesh, health checks