Skip to content

Django App Structure

This page documents how Django apps are organized in Arctyk ITSM.

Project Structure

arctyk-itsm/
├── src/
│   ├── config/          # Project settings
│   ├── tickets/         # Ticket management app
│   ├── projects/        # Project organization app
│   ├── assets/          # IT asset tracking app
│   ├── users/           # User management app
│   ├── changelog/       # Change tracking app (v0.6.0+)
│   └── core/            # Shared utilities
├── templates/           # Project-level templates
├── static/              # Compiled static files
├── STATIC_SRC/          # Source SCSS/JS
├── manage.py
└── requirements.txt

App Organization

Each Django app follows this structure:

tickets/
├── __init__.py
├── admin.py          # Django admin customization
├── apps.py           # App configuration
├── constants.py      # App-level constants
├── forms.py          # Django forms
├── models.py         # Database models
├── signals.py        # Django signals
├── urls.py           # URL routing
├── views.py          # View functions/classes
├── workflows.py      # Workflow logic
├── migrations/       # Database migrations
├── templates/        # App templates
│   └── tickets/
│       ├── ticket_list.html
│       └── ticket_detail.html
└── tests/            # Unit tests
    ├── test_models.py
    ├── test_views.py
    └── test_forms.py

Core Apps

tickets

Purpose: Ticket management and workflow

Key Files:

  • models.py - Ticket, RecurringTaskTemplate, RecurringTicketRun models
  • forms.py - TicketForm, TicketFilterForm
  • views.py - CRUD views for tickets
  • workflows.py - Status transition logic
  • constants.py - Status choices, categories
  • tasks.py - Celery background task definitions
  • signals.py - Auto-increment ticket numbers, email notifications

Key Features (v0.6.0+):

  • SLA tracking with response_target and resolution_target fields
  • Lifecycle timestamps: created_at, first_responded_at, resolved_at, closed_at
  • Rich text descriptions with TinyMCE integration
  • Comment integration via Comment model

projects

Purpose: Project organization and tracking

Key Files:

  • models.py - Project model
  • views.py - Project management views

assets

Purpose: IT asset inventory management

Key Files:

  • models.py - Asset model
  • views.py - Asset CRUD views

users

Purpose: User authentication and management

Key Files:

  • models.py - Extended User model
  • views.py - Profile, settings views

core

Purpose: Shared utilities across apps

Key Files:

  • utils.py - Utility functions
  • mixins.py - View mixins
  • decorators.py - Custom decorators

changelog

Purpose: Automatic change tracking and audit trail (new in v0.6.0)

Key Files:

  • models.py - ChangeLog model with GenericForeignKey
  • signals.py - Post-save signal handlers for all models
  • middleware.py - Captures current user for audit trail
  • views.py - Change history display views
  • admin.py - ChangeLog admin configuration

Features:

  • Automatic tracking of all model changes
  • Captures who changed what, when, with IP address
  • Works universally via GenericForeignKey (not limited to specific models)

Configuration

config/settings.py

Main Django settings:

INSTALLED_APPS = [
    # Django apps
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    # Third-party apps
    'rest_framework',

    # Project apps
    'tickets',
    'projects',
    'assets',
    'users',
    'changelog',
    'core',
]

config/urls.py

Main URL routing:

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('tickets.urls')),
    path('projects/', include('projects.urls')),
    path('assets/', include('assets.urls')),
    path('api/', include('api.urls')),
]

Best Practices

  1. Keep apps focused - Each app should have a single responsibility
  2. Use app namespaces - Template and URL namespacing prevents conflicts
  3. Share common code - Put shared utilities in core/
  4. Test thoroughly - Each app should have comprehensive tests
  5. Document dependencies - Document inter-app relationships