Core App Architecture

Domain Responsibility

What This App Owns

• BaseModel foundation with lifecycle hooks
• Utility clients for external services (ES, S3, Redis, Slack, Pusher, DocumentDB)
• Middleware for authentication, sessions, and request handling
• Decorators for common view patterns
• Shared utilities (date, encryption, translation, PDF, image processing)

What It Depends On

• Django framework
• External service SDKs (boto3, elasticsearch, redis-py)

What Should NOT Be Added Here

• Domain-specific business logic (belongs in domain apps)
• Feature-specific models (belongs in domain apps)
• API endpoints for specific features

Model-Centric Design (Fat Models)

Key Models

Business Logic in Models

BaseModel (core/models/base.py)

ActivityLogBase (core/models/activity_log_base.py)

Why Fat Model Style Here

The core app provides infrastructure mixins, not domain logic. Models in domain apps inherit from BaseModel to get:

1. Consistent lifecycle hooks
2. Activity logging capability
3. Caching utilities
4. Slack notifications

Invariants & Data Rules

BaseModel Constraints

• save() always calls validate() → before_save() → super().save() → after_save()
• If validate() raises ValidationError, save is aborted
• after_save() runs INSIDE the transaction (careful with external calls)

Cache Keys

• Format: {ModelName}_CentreId{lab_id}_List or custom cache_key
• TTL: default_cache_ttl = 7 * 24 * 60 * 60 (7 days)

Data Access Patterns

Cache Access

# Redis hash-based caching
instance = cache.hget(cls.cache_key, instance_id)
if not instance:
    instance = cls.get(pk=instance_id)
    cache.hset(cls.cache_key, instance_id, json.dumps(serialized))

Client Factory Pattern

# core/utils/clients.py
client = get_client("es")       # ElasticSearchClient
client = get_client("s3")       # S3Client
client = get_client("slack")    # SlackClient
client = get_client("fusion")   # FusionClient
client = get_client("docdb", account_id=123)  # DocumentDBClient

API Layer

The core app exposes minimal endpoints:

GenericView Base Class

# core/view.py
class GenericView(View):
    """Base view with session utilities"""
    
    def get_lab_id_from_session(self, session):
        """Extract lab_id from session"""
        return session.get("labId") or session.get("docLabId")
    
    def get_child_lab_ids(self, parent_lab_id):
        """Get child labs for multi-tenant queries"""
        return LabRelations.get_child_labs(parent_lab_id)

Integrations

External Services

Service Client Example

# core/utils/clients.py
def get_client(service: str, account_id=None, ...):
    if service == "es":
        return ElasticSearchClient(config=settings.ES_CONFIG)
    elif service == "s3":
        return S3Client()
    elif service == "slack":
        return SlackClient()
    # ... more clients

Side Effects & Hidden Coupling

No Django Signals

The core app does NOT use signals.py. All side effects are explicit in model methods.

Coupling Points

Performance & Scaling Notes

Hot Paths

• cache.hget() / cache.hset() - Redis operations per request
• get_client("es") - Client instantiation (consider pooling)

Caching Strategy

• Model instances cached in Redis hashes by (model_key, instance_id)
• TTL is 7 days by default
• Manual invalidation via reset_cache_instance(instance_id)

Safe Extension Guide

Adding a New Utility Client

1. Create client in core/utils/{service_name}/client.py
2. Register in core/utils/clients.py:

   elif service == "new_service":
       return NewServiceClient(**args)

3. Add settings in config/settings/

Adding a New Mixin

1. Create mixin in core/models/{mixin_name}.py
2. Add to BaseModel's parent classes if universally needed
3. Or inherit in specific domain models

Patterns to Follow

• Keep utilities stateless
• Use dependency injection via get_client()
• Log errors to Sentry

Patterns to Avoid

• Domain logic in core/
• Direct database queries without going through models
• Synchronous external calls in hot paths

File Map