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**
```python
# 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**
```python
# 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

```html
<!-- 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

```python
# 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)

```html
<!-- 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**
```html
{% extends "base.html" %}
{% block content %}...{% endblock %}
```

### 3. **Centralize Configuration**
```python
# Don't hardcode
app_name = "SwiftOps API"

# Do this
from app.constants.app_metadata import APP_NAME
```

### 4. **Include Request Object**
```python
# Always pass request to templates
return templates.TemplateResponse("page.html", {
    "request": request,  # Required by Jinja2Templates
    "data": data
})
```

### 5. **Use url_for for Static Files**
```html
<!-- 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`:

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

### Add Custom Styles

Edit `static/css/main.css`:

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

### Add Custom JavaScript

Edit `static/js/main.js`:

```javascript
// 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](https://fastapi.tiangolo.com/advanced/templates/)
- [Jinja2 Documentation](https://jinja.palletsprojects.com/)
- [Static Files in FastAPI](https://fastapi.tiangolo.com/tutorial/static-files/)
- [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)

---

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