TimeTracker/docs/implementation-notes/QUICK_START_ARCHITECTURE.md

Quick Start: Using the New Architecture

This guide shows you how to use the new service layer, repository pattern, and other improvements.

---

🏗️ Architecture Overview

Routes → Services → Repositories → Models → Database

Layers

1. Routes - Handle HTTP requests/responses
2. Services - Business logic
3. Repositories - Data access
4. Models - Database models
5. Schemas - Validation and serialization

---

📝 Quick Examples

Using Services in Routes

Before:

@route('/timer/start')
def start_timer():
    project = Project.query.get(project_id)
    if not project:
        return error
    timer = TimeEntry(...)
    db.session.add(timer)
    db.session.commit()

After:

from app.services import TimeTrackingService

@route('/timer/start')
def start_timer():
    service = TimeTrackingService()
    result = service.start_timer(user_id, project_id)
    if result['success']:
        return success_response(result['timer'])
    return error_response(result['message'])

Using Repositories

from app.repositories import TimeEntryRepository

repo = TimeEntryRepository()
entries = repo.get_by_user(user_id, include_relations=True)
active_timer = repo.get_active_timer(user_id)

Using Schemas for Validation

from app.schemas import TimeEntryCreateSchema
from app.utils.api_responses import validation_error_response

@route('/api/time-entries', methods=['POST'])
def create_entry():
    schema = TimeEntryCreateSchema()
    try:
        data = schema.load(request.get_json())
    except ValidationError as err:
        return validation_error_response(err.messages)
    
    # Use validated data...

Using API Response Helpers

from app.utils.api_responses import (
    success_response,
    error_response,
    paginated_response,
    created_response
)

# Success response
return success_response(data=project.to_dict(), message="Project created")

# Error response
return error_response("Project not found", error_code="not_found", status_code=404)

# Paginated response
return paginated_response(
    items=projects,
    page=1,
    per_page=50,
    total=100
)

# Created response
return created_response(data=project.to_dict(), location=f"/api/projects/{project.id}")

Using Constants

from app.constants import ProjectStatus, TimeEntrySource, InvoiceStatus

# Use enums instead of magic strings
project.status = ProjectStatus.ACTIVE.value
entry.source = TimeEntrySource.MANUAL.value
invoice.status = InvoiceStatus.DRAFT.value

Using Query Optimization

from app.utils.query_optimization import eager_load_relations, optimize_list_query

# Eagerly load relations to prevent N+1 queries
query = Project.query
query = eager_load_relations(query, Project, ['client', 'time_entries'])

# Or use auto-optimization
query = optimize_list_query(Project.query, Project)

Using Validation Utilities

from app.utils.validation import (
    validate_required,
    validate_date_range,
    validate_email,
    sanitize_input
)

# Validate required fields
validate_required(data, ['name', 'email'])

# Validate date range
validate_date_range(start_date, end_date)

# Validate email
email = validate_email(data['email'])

# Sanitize input
clean_input = sanitize_input(user_input, max_length=500)

---

🔄 Migration Guide

Step 1: Identify Business Logic

Find code in routes that:

• Validates data
• Performs calculations
• Checks permissions
• Creates/updates multiple models
• Has complex conditional logic

Step 2: Extract to Service

Move business logic to a service method:

# app/services/my_service.py
class MyService:
    def do_something(self, param1, param2):
        # Business logic here
        return {'success': True, 'data': result}

Step 3: Use Repository for Data Access

Replace direct model queries with repository calls:

# Before
projects = Project.query.filter_by(status='active').all()

# After
repo = ProjectRepository()
projects = repo.get_active_projects()

Step 4: Update Route

Use service in route:

@route('/endpoint')
def my_endpoint():
    service = MyService()
    result = service.do_something(param1, param2)
    if result['success']:
        return success_response(result['data'])
    return error_response(result['message'])

---

🧪 Testing

Testing Services

from unittest.mock import Mock
from app.services import TimeTrackingService

def test_start_timer():
    service = TimeTrackingService()
    service.time_entry_repo = Mock()
    service.project_repo = Mock()
    
    result = service.start_timer(user_id=1, project_id=1)
    assert result['success'] == True

Testing Repositories

from app.repositories import TimeEntryRepository

def test_get_active_timer(db_session, user, project):
    repo = TimeEntryRepository()
    timer = repo.create_timer(user.id, project.id)
    db_session.commit()
    
    active = repo.get_active_timer(user.id)
    assert active.id == timer.id

---

📚 Additional Resources

• Full Documentation: See IMPLEMENTATION_SUMMARY.md
• API Documentation: See docs/API_ENHANCEMENTS.md
• Example Code: See app/routes/projects_refactored_example.py
• Test Examples: See tests/test_services/ and tests/test_repositories/

---

✅ Best Practices

1. Always use services for business logic - Don't put business logic in routes
2. Use repositories for data access - Don't query models directly in routes
3. Use schemas for validation - Don't validate manually
4. Use response helpers - Don't create JSON responses manually
5. Use constants - Don't use magic strings
6. Eager load relations - Prevent N+1 queries
7. Handle errors consistently - Use error response helpers

---

Happy coding! 🚀