Architecture & Design Decisions

Overview

This document explains the architectural decisions made in the AI Usage Learning Platform and how they satisfy the functional and non-functional requirements.

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Presentation Layer                    │
│  (Django Templates + Bootstrap 5 + Chart.js)                │
│  - Login/Register                                            │
│  - Dashboard with visualizations                             │
│  - Usage logging forms                                       │
│  - Insights display                                          │
│  - Feedback forms                                            │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                        Application Layer                     │
│  (Django Views + Forms)                                      │
│  - Authentication (login, register, logout)                  │
│  - Dashboard data aggregation                                │
│  - Usage log management                                      │
│  - Insight generation                                        │
│  - Feedback handling                                         │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                        Business Logic Layer                  │
│  (Models + Signals)                                          │
│  - UserProfile (extended user data)                          │
│  - AIUsageLog (usage tracking)                               │
│  - AIEthicsPolicy (compliance rules)                         │
│  - ComplianceStatus (compliance evaluation)                  │
│  - UserInsight (automated insights)                          │
│  - UserFeedback (user feedback)                              │
│  - Signals (auto profile creation, insight generation)       │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                        Data Layer                            │
│  (Django ORM + SQLite)                                       │
│  - User authentication data                                  │
│  - AI usage logs                                             │
│  - Policies and compliance data                              │
│  - Insights and feedback                                     │
└─────────────────────────────────────────────────────────────┘

Design Patterns

1. Model-View-Template (MVT)

Why: Django's standard pattern ensures separation of concerns.

Models: Data structure and business logic
Views: Request handling and data processing
Templates: Presentation logic

2. Repository Pattern (via Django ORM)

Why: Abstracts database operations and makes the code database-agnostic.

Example:

AIUsageLog.objects.filter(user=user).order_by('-timestamp')

3. Observer Pattern (Django Signals)

Why: Automatically trigger actions when certain events occur.

Example:

@receiver(post_save, sender=User)
def create_user_profile(sender, instance, created, **kwargs):
    if created:
        UserProfile.objects.create(user=instance)

4. Form Validation Pattern

Why: Centralized validation and security.

Example:

class AIUsageLogForm(forms.ModelForm):
    class Meta:
        model = AIUsageLog
        fields = [...]

Data Model Design

Entity Relationship Diagram

User (Django Auth)
  │
  ├─── 1:1 ──→ UserProfile
  │
  ├─── 1:N ──→ AIUsageLog
  │                 │
  │                 └─── N:1 ──→ AIEthicsPolicy
  │
  ├─── 1:N ──→ ComplianceStatus
  │                 │
  │                 └─── N:1 ──→ AIEthicsPolicy
  │
  ├─── 1:N ──→ UserInsight
  │                 │
  │                 └─── N:M ──→ AIUsageLog (related_usage_logs)
  │
  └─── 1:N ──→ UserFeedback

Why This Structure?

UserProfile extends User: Keeps authentication separate from profile data (Single Responsibility Principle)
AIEthicsPolicy is independent: Allows multiple versions and policies to coexist
AIUsageLog references Policy: Tracks which policy was active at the time of usage
ComplianceStatus is calculated: Periodic snapshots of compliance for historical tracking
UserInsight can reference logs: Allows detailed insights based on specific usage patterns

Functional Requirements Mapping

1. Personalized AI Usage Dashboard ✅

Implementation:

dashboard_view() aggregates user-specific data
User-filtered queries: AIUsageLog.objects.filter(user=request.user)
Statistics: total, today, week, month usage counts
Compliance percentage calculation

Files:

views.py - dashboard_view()
dashboard.html

2. Visualizations of AI Usage ✅

Implementation:

Chart.js integration in base template
Three chart types:
- Line chart: Daily usage trend (30 days)
- Pie chart: Usage by AI tool
- Bar chart: Usage by type
Data passed as JSON from Django to JavaScript

Files:

dashboard.html - Chart rendering

3. Feedback Submission ✅

Implementation:

UserFeedback model with file upload support
Status tracking workflow
Admin panel for reviewing feedback

Files:

models.py - UserFeedback
views.py - feedback_view()
feedback.html

4. Policy Management ✅

Implementation:

AIEthicsPolicy model with versioning
Admin interface for CRUD operations
Active policy detection with date ranges
Compliance evaluation against policies

Files:

models.py - AIEthicsPolicy
admin.py - Admin configuration

5. User Login ✅

Implementation:

Django authentication system
Login, register, logout views
Login required decorator for protected views
Session management

Files:

views.py - Authentication views
urls.py - Route configuration

6. AI Usage Insights ✅

Implementation:

Automated insight generation via signals
Different insight types: patterns, compliance, achievements, warnings
Priority-based display
Read/dismiss functionality

Files:

models.py - UserInsight
signals.py - Automatic generation
insights.html

Non-Functional Requirements

Usability ✅

Implementation:

Bootstrap 5 for responsive, professional UI
Intuitive navigation with sidebar
Clear visual hierarchy
Contextual help text
Error messages and success confirmations

Evidence: Consistent UI patterns, clear calls-to-action, minimal clicks to complete tasks

GDPR Compliance ✅

Implementation:

Consent Tracking: data_collection_consent field with timestamp
Data Access: Users can view all their data via dashboard
Data Export: JSON export of all user data (export_data_view)
Data Deletion: Cascade delete on user removal
Privacy Controls: Granular settings for analytics and notifications
Transparency: Clear privacy information in profile

Files:

models.py - Consent fields
views.py - export_data_view()
profile.html - Privacy controls

Security Decisions

1. CSRF Protection

Why: Prevents cross-site request forgery attacks How: Django's CSRF middleware + {% csrf_token %} in forms

2. Password Security

Why: Protects user accounts How: Django's password validators + hashing (PBKDF2)

3. SQL Injection Prevention

Why: Prevents database attacks How: Django ORM automatically parameterizes queries

4. XSS Prevention

Why: Prevents script injection How: Django template auto-escaping

5. Session Security

Why: Protects user sessions How: HTTPOnly cookies, SameSite flag, 2-hour timeout

6. Login Required Decorator

Why: Protects sensitive views How: @login_required on all dashboard views

Technology Choices

Django 4+

Why:

Mature, battle-tested framework
Excellent ORM for database operations
Built-in authentication and admin
Strong security features
Large ecosystem and community

Alternatives Considered: Flask (too minimal), FastAPI (REST-focused)

SQLite

Why:

Zero configuration
Perfect for development and small deployments
Single file database (easy backup)
Can migrate to PostgreSQL later

Production Alternative: PostgreSQL for better concurrency

Bootstrap 5

Why:

Professional UI components
Responsive out of the box
Extensive documentation
No build process needed

Alternatives Considered: Tailwind (requires build), Material UI (heavier)

Chart.js

Why:

Lightweight (64KB)
Beautiful, responsive charts
Simple API
No jQuery dependency

Alternatives Considered: D3.js (steeper learning curve), Plotly (heavier)

Scalability Considerations

Current Scale

Suitable for: 100-1000 users
Database: SQLite (up to ~100 concurrent users)
Storage: File system for uploads

Future Scaling

If needed to scale to 10,000+ users:

Database: Migrate to PostgreSQL

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        # ...
    }
}

Caching: Add Redis for session storage and query caching

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://127.0.0.1:6379/1',
    }
}

File Storage: Move to cloud storage (S3, Azure Blob)

DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'

Load Balancing: Deploy multiple application servers behind nginx
Database Optimization: Add indexes, use select_related/prefetch_related
```
AIUsageLog.objects.select_related('user', 'policy').filter(...)
```

Testing Strategy

Unit Tests

Model methods (compliance checking, validation)
Form validation
Signal handlers

Integration Tests

View responses
Authentication flow
Dashboard data aggregation

Manual Testing Checklist

Performance Optimizations

Implemented

Database Indexes: On frequently queried fields

indexes = [
    models.Index(fields=['user', '-timestamp']),
]

Query Optimization: Limit results in recent activity

recent_logs = AIUsageLog.objects.filter(user=user)[:10]

Pagination: For usage history (25 per page)
Chart Data Limiting: Last 30 days only for trend chart

Future Optimizations

Query result caching
Database connection pooling
Static file CDN
Lazy loading for images
Background tasks for insight generation (Celery)

Maintenance & Extensibility

Adding New Features

Example: Add a new AI tool

Update model choices:

AI_TOOL_CHOICES = [
    # ... existing
    ('new_tool', 'New AI Tool'),
]

Create and run migration:

python manage.py makemigrations
python manage.py migrate

No template changes needed (dynamic rendering)

Code Organization

dashboard/
├── models.py       # Data models (single source of truth)
├── views.py        # Request handlers (business logic)
├── forms.py        # Form validation (input handling)
├── urls.py         # URL routing (API endpoints)
├── admin.py        # Admin configuration (management)
├── signals.py      # Event handlers (automation)
└── tests.py        # Test cases (quality assurance)

Benefits:

Clear separation of concerns
Easy to locate functionality
Maintainable and testable

Deployment Checklist

Before production deployment:

Conclusion

This architecture provides:

✅ Clean separation of concerns
✅ Scalability path
✅ Security by default
✅ Easy maintenance
✅ GDPR compliance
✅ Comprehensive testing
✅ Professional user experience

The design supports all functional requirements while maintaining code quality and extensibility.

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

Architecture & Design Decisions

Overview

System Architecture

High-Level Architecture

Design Patterns

1. Model-View-Template (MVT)

2. Repository Pattern (via Django ORM)

3. Observer Pattern (Django Signals)

4. Form Validation Pattern

Data Model Design

Entity Relationship Diagram

Why This Structure?

Functional Requirements Mapping

1. Personalized AI Usage Dashboard ✅

2. Visualizations of AI Usage ✅

3. Feedback Submission ✅

4. Policy Management ✅

5. User Login ✅

6. AI Usage Insights ✅

Non-Functional Requirements

Usability ✅

GDPR Compliance ✅

Security Decisions

1. CSRF Protection

2. Password Security

3. SQL Injection Prevention

4. XSS Prevention

5. Session Security

6. Login Required Decorator

Technology Choices

Django 4+

SQLite

Bootstrap 5

Chart.js

Scalability Considerations

Current Scale

Future Scaling

Testing Strategy

Unit Tests

Integration Tests

Manual Testing Checklist

Performance Optimizations

Implemented

Future Optimizations

Maintenance & Extensibility

Adding New Features

Code Organization

Deployment Checklist

Conclusion