docs/dev/comms/TEMPLATES_ARCHITECTURE.md

SwiftOps API - Templates Architecture

🏗️ Architecture Overview

Following FastAPI best practices, we've separated concerns into distinct layers:

src/app/
├── templates/              # Jinja2 HTML templates
│   ├── base.html          # Base template (layout)
│   ├── index.html         # Landing page
│   └── README.md          # Template documentation
│
├── static/                # Static assets
│   ├── css/
│   │   └── main.css      # Styles (theme-aware)
│   └── js/
│       └── main.js       # Client-side JavaScript
│
├── api/v1/
│   ├── pages.py          # Page routes (HTML)
│   ├── auth.py           # API routes (JSON)
│   └── ...               # Other API routes
│
├── constants/
│   └── app_metadata.py   # Centralized app config
│
└── main.py               # Application entry point

---

📋 Design Principles

1. Separation of Concerns

• Templates (templates/) - HTML structure
• Styles (static/css/) - Visual presentation
• Scripts (static/js/) - Client behavior
• Routes (api/v1/pages.py) - Page logic
• Config (constants/app_metadata.py) - Metadata

2. Template Inheritance

base.html (layout)
    ↓
index.html (content)
    ↓
Future pages extend base.html

3. Static File Serving

# Mounted in main.py
app.mount("/static", StaticFiles(directory="static"), name="static")

# Used in templates
<link rel="stylesheet" href="{{ url_for('static', path='/css/main.css') }}">

4. Centralized Configuration

# constants/app_metadata.py
APP_NAME = "SwiftOps API"
APP_VERSION = "1.0.0"

# Used everywhere
from app.constants.app_metadata import APP_NAME, APP_VERSION

---

🎨 Features

Theme Support

• ✅ Automatic dark/light mode detection
• ✅ Respects system preferences
• ✅ Smooth transitions
• ✅ CSS custom properties (variables)

Responsive Design

• ✅ Mobile-first approach
• ✅ Flexible grid layouts
• ✅ Touch-friendly interactions
• ✅ Breakpoints for all devices

Performance

• ✅ Minimal CSS/JS
• ✅ No external dependencies
• ✅ Fast page loads
• ✅ Optimized assets

---

📝 Adding New Pages

Step 1: Create Template

<!-- templates/about.html -->
{% extends "base.html" %}

{% block title %}About - {{ app_name }}{% endblock %}

{% block content %}
<div class="container">
    <h1>About {{ app_name }}</h1>
    <p>{{ app_description }}</p>
</div>
{% endblock %}

Step 2: Add Route

# api/v1/pages.py
@router.get("/about", response_class=HTMLResponse)
async def about(request: Request):
    return templates.TemplateResponse("about.html", {
        "request": request,
        "app_name": APP_NAME,
        "app_description": APP_DESCRIPTION
    })

Step 3: Update Navigation (if needed)

<!-- templates/base.html -->
<nav>
    <a href="/">Home</a>
    <a href="/about">About</a>
</nav>

---

🎯 Best Practices

1. Keep Templates Simple

• Logic in Python (routes)
• Presentation in HTML (templates)
• Styling in CSS (separate file)

2. Use Template Inheritance

{% extends "base.html" %}
{% block content %}...{% endblock %}

3. Centralize Configuration

# Don't hardcode
app_name = "SwiftOps API"

# Do this
from app.constants.app_metadata import APP_NAME

4. Include Request Object

# Always pass request to templates
return templates.TemplateResponse("page.html", {
    "request": request,  # Required by Jinja2Templates
    "data": data
})

5. Use url_for for Static Files

<!-- Good -->
<link href="{{ url_for('static', path='/css/main.css') }}">

<!-- Avoid -->
<link href="/static/css/main.css">

---

🔧 Customization

Update App Metadata

Edit constants/app_metadata.py:

APP_NAME = "Your App Name"
APP_VERSION = "2.0.0"
APP_DESCRIPTION = "Your description"

Add Custom Styles

Edit static/css/main.css:

/* Add your custom styles */
.custom-class {
    color: var(--accent-color);
}

Add Custom JavaScript

Edit static/js/main.js:

// Add your custom scripts
document.addEventListener('DOMContentLoaded', function() {
    // Your code here
});

---

📊 File Structure Benefits

✅ Maintainability

• Clear separation of concerns
• Easy to find and update files
• Consistent structure

✅ Scalability

• Add new pages easily
• Extend base template
• Reuse components

✅ Testability

• Routes are separate from templates
• Logic is in Python (testable)
• Templates are pure HTML

✅ Performance

• Static files cached by browser
• Minimal dependencies
• Fast rendering

---

🚀 Future Enhancements

Planned Features

• Component library (reusable blocks)
• Admin dashboard template
• Error pages (404, 500)
• Email templates
• PDF generation templates

Possible Additions

• Template fragments (HTMX support)
• Internationalization (i18n)
• Template caching
• Asset bundling/minification

---

📚 Resources

• FastAPI Templates
• Jinja2 Documentation
• Static Files in FastAPI
• CSS Custom Properties

---

This architecture provides a solid foundation for building scalable, maintainable web pages in your FastAPI application! 🎉