Architecture Overview¶

This section provides a comprehensive overview of Arctyk ITSM's architecture, from high-level system design to detailed implementation specifics.

System Architecture¶

Arctyk ITSM is a modern web application built on Django, following a monolithic architecture with clear separation of concerns.

┌─────────────────────────────────────────────┐
│           Browser (User Interface)          │
└────────────┬────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────┐
│      Django Application (Web Server)        │
│  ┌────────────┬──────────┬────────────────┐ │
│  │   Views    │Templates │   Static Files │ │
│  └────────────┴──────────┴────────────────┘ │
│  ┌────────────┬──────────┬────────────────┐ │
│  │   Models   │  Forms   │      API       │ │
│  └────────────┴──────────┴────────────────┘ │
└────────────┬────────────────────────────────┘
             │
    ┌────────┴────────┐
    ▼                 ▼
┌──────────┐    ┌─────────────┐
│PostgreSQL│    │Celery+Redis │
│ Database │    │ Task Queue  │
└──────────┘    └─────────────┘

Core Components¶

Django Web Framework¶

• Version: 5.2.9 LTS
• Purpose: Main application framework
• Key Apps:
• tickets - Ticket management
• projects - Project organization
• assets - IT asset tracking
• users - Authentication and user management

PostgreSQL Database¶

• Version: 15+
• Purpose: Primary data storage
• Key Features:
• ACID compliance
• Full-text search
• JSON field support
• Robust migrations

Celery Task Queue¶

• Purpose: Asynchronous task processing
• Broker: Redis
• Use Cases:
• Email notifications
• Scheduled reports
• Bulk operations
• External API calls

Redis Cache¶

• Purpose: Caching and message broker
• Use Cases:
• Session storage
• Query caching
• Celery message broker
• Rate limiting

Architecture Principles¶

1. Django Apps¶

Each feature is organized as a Django app with clear boundaries:

src/
├── tickets/        # Ticket management
├── projects/       # Project tracking
├── assets/         # Asset inventory
├── users/          # User management
└── config/         # Project settings

2. Template Hierarchy¶

Templates follow inheritance patterns for consistency:

base.html
  └── layouts/_layout_wrapper.html
      └── tickets/ticket_list.html

See Template Architecture for details.

3. API Design¶

RESTful API endpoints follow Django REST Framework conventions:

GET    /api/tickets/          # List tickets
POST   /api/tickets/          # Create ticket
GET    /api/tickets/{id}/     # Get ticket
PUT    /api/tickets/{id}/     # Update ticket
DELETE /api/tickets/{id}/     # Delete ticket

4. Workflow Engine¶

Ticket workflows follow a category-based transition system similar to Jira. See Workflows for details.

Key Architectural Decisions¶

Why Django?¶

• Mature, battle-tested framework
• Excellent ORM for database operations
• Built-in admin interface
• Strong security defaults
• Large ecosystem of packages

Why PostgreSQL?¶

• Advanced features (JSONB, full-text search)
• Better performance for complex queries
• Strong data integrity
• Excellent Django support

Why Celery?¶

• Reliable task queue
• Delayed task execution
• Retry mechanisms
• Monitoring and logging

Why Monolithic Architecture?¶

• Simpler deployment
• Easier development for small teams
• Shared database transactions
• Lower operational overhead

Request/Response Flow¶

Standard Page Request¶

1. Browser → Django View
2. View → Models (Database query)
3. Models → View (Data)
4. View → Template (Render)
5. Template → Browser (HTML)

AJAX Request¶

1. Browser → Django View (AJAX)
2. View → Models (Database query)
3. Models → View (Data)
4. View → Browser (JSON response)
5. JavaScript → DOM update

Security Architecture¶

Authentication¶

• Django's built-in authentication system
• Session-based authentication for web
• Token-based authentication for API
• Password hashing with PBKDF2

Authorization¶

• Django permissions system
• Role-based access control (RBAC)
• Object-level permissions
• View decorators and mixins

CSRF Protection¶

• CSRF tokens on all forms
• SameSite cookie attributes
• HTTPS enforcement in production

See Authentication & Authorization for details.

Data Flow¶

Create Ticket Flow¶

1. User submits form
2. View validates form
3. Form validates workflow transition
4. Model saves to database
5. Signal triggers changelog creation
6. Celery task sends notifications
7. View returns success response

Ticket List Flow¶

1. User requests ticket list
2. View queries tickets with filters
3. Queryset applies permissions
4. Pagination applied
5. Template renders list
6. Partial templates (sidebar, breadcrumbs) included
7. HTML returned to browser

Performance Considerations¶

Database Optimization¶

• Selective use of select_related() and prefetch_related()
• Database indexing on frequently queried fields
• Query optimization with Django Debug Toolbar

Caching Strategy¶

• Template fragment caching
• Query caching with Redis
• Static file caching with CDN (production)

Asset Optimization¶

• SCSS compilation to minified CSS
• JavaScript bundling (future enhancement)
• Static file compression

Scalability Path¶

Current architecture supports small to medium deployments. For larger scale:

Horizontal Scaling¶

• Add more web server instances behind load balancer
• Separate Celery workers for different task types
• Read replicas for database

Vertical Scaling¶

• Increase database resources
• Add more Redis nodes
• Upgrade server specifications

Optimization Opportunities¶

• Implement database connection pooling
• Add CDN for static assets
• Enable database query caching
• Implement full-text search with PostgreSQL

Deployment Architecture¶

Development¶

Docker Compose
├── web (Django dev server)
├── db (PostgreSQL)
├── redis
└── celery worker

Production¶

DigitalOcean Droplet
├── Nginx (Reverse proxy, static files)
├── Gunicorn (WSGI server)
├── PostgreSQL (Database)
├── Redis (Cache/broker)
└── Celery (Background tasks)

See Deployment for details.

Related Documentation¶

• System Design - Detailed system architecture
• Database Schema - ER diagrams and relationships
• App Structure - Django app organization
• Frontend Architecture - UI and JavaScript patterns
• Workflows - Ticket workflow engine
• Authentication - Security and access control
• Celery Tasks - Background job processing

Architecture Diagrams¶

Component Diagram¶

┌─────────────┐     ┌──────────────┐
│   Browser   │────▶│    Nginx     │
└─────────────┘     └──────┬───────┘
                           │
                    ┌──────▼────────┐
                    │   Gunicorn    │
                    │   (Django)    │
                    └──┬─────────┬──┘
                       │         │
          ┌────────────▼──┐   ┌──▼──────────┐
          │  PostgreSQL   │   │   Redis     │
          │   Database    │   │ Cache/Queue │
          └───────────────┘   └──┬──────────┘
                                 │
                          ┌──────▼──────┐
                          │   Celery    │
                          │   Workers   │
                          └─────────────┘

Technology Stack Summary¶

Next Steps¶

1. Deep dive into System Design
2. Understand Database Schema
3. Explore App Structure
4. Learn about Workflows