MTAV Stack

Multi-repository architecture for MTAV application

This is an orchestrator repository that brings together independent backend and frontend services through Docker Compose. The architecture enables maximum flexibility - swap any component without affecting others.

Architecture

mtav-stack/                      # This repo (orchestrator)
├── docker-compose.yml           # Service orchestration
├── mtav                         # Unified development script
├── .env.example                 # Environment template
├── api/                         # Git submodule → mtav-api
│   └── Django REST API
└── spa/                         # Git submodule → mtav-spa
    └── React SPA

Repositories

1. mtav-stack (this repo)

• Purpose: Orchestration and development environment
• Contains: Docker setup, scripts, integration configuration
• URL: TBD (will be created)

2. mtav-api (submodule in api/)

• Purpose: Backend REST API (framework-agnostic)
• Current: Django REST Framework
• Contract: REST API endpoints + JSON schemas
• Swappable: Django, Rails, Laravel (without Inertia), FastAPI, etc.
• URL: TBD (will be created)

3. mtav-spa (submodule in spa/)

• Purpose: Frontend SPA (backend-agnostic)
• Current: React + TypeScript
• Contract: Consumes REST API from any backend
• Swappable: React, Vue, Svelte, Angular, etc.
• URL: TBD (will be created)

Quick Start

First Time Setup

# Clone with submodules
git clone --recursive [mtav-stack-url]
cd mtav-stack

# Or if already cloned without submodules
git submodule update --init --recursive

# Start everything
./mtav up

Daily Development

./mtav up           # Start all services
./mtav logs         # View logs
./mtav test         # Run all tests
./mtav down         # Stop everything

Services

When running, the following services are available:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000/api
• API Docs: http://localhost:8000/api/docs/
• Admin Panel: http://localhost:8000/admin
• MailHog: http://localhost:8025
• PostgreSQL: localhost:5432
• Redis: localhost:6379

API Contract

The backend and frontend communicate solely through a REST API contract:

Authentication

• POST /api/auth/register/ - User registration
• POST /api/auth/login/ - User login (returns JWT)
• POST /api/auth/refresh/ - Refresh access token
• GET /api/auth/me/ - Get current user

Resources

• GET|POST /api/projects/ - Projects list/create
• GET|PUT|DELETE /api/projects/{id}/ - Project detail
• GET|POST /api/families/ - Families list/create
• GET|PUT|DELETE /api/families/{id}/ - Family detail
• GET|POST /api/units/ - Units list/create
• ... (see API docs at http://localhost:8000/api/docs/)

Data Format

All requests/responses use JSON with standard REST conventions.

Swapping Components

Swap Backend (e.g., Django → Rails)

cd mtav-stack
git submodule deinit api
git rm api
git submodule add [mtav-rails-api-url] api
./mtav rebuild backend

The new backend just needs to implement the same REST contract.

Swap Frontend (e.g., React → Vue)

cd mtav-stack
git submodule deinit spa
git rm spa
git submodule add [mtav-vue-spa-url] spa
./mtav rebuild frontend

The new frontend just needs to consume the same REST API.

Development Workflow

Working on Backend Only

cd api/
# Make changes
git add .
git commit -m "Add feature"
git push

# Back to orchestrator to update reference
cd ..
git add api
git commit -m "Update api submodule"
git push

Working on Frontend Only

cd spa/
# Make changes
git add .
git commit -m "Add component"
git push

# Back to orchestrator to update reference
cd ..
git add spa
git commit -m "Update spa submodule"
git push

Working on Integration

Changes to docker-compose.yml, mtav script, or environment setup are done in this repo directly.

Why This Structure?

vs. Monorepo (Laravel + Inertia)

• Inertia: Tightly couples frontend and backend (server-driven routing, shared types)
• This: Loose coupling via REST API contract
• Benefit: Swap either side independently

vs. Separate Repos Without Orchestrator

• Problem: Each developer needs to configure Docker, scripts, integration
• This: One clone gets everything working
• Benefit: Unified development experience

vs. Single Repo

• Problem: Frontend and backend version together, harder team separation
• This: Independent versioning and teams
• Benefit: Backend team and frontend team work independently

Testing

# All tests
./mtav test

# Backend only
./mtav test-backend

# Frontend only
./mtav test-frontend

# With coverage
./mtav coverage

Production Deployment

# Build production images
./mtav build production

# Deploy (configure for your platform)
./mtav deploy

Environment Variables

Copy .env.example to .env and configure:

# Django
DEBUG=True
SECRET_KEY=your-secret-key
DATABASE_URL=postgresql://user:pass@db:5432/mtav

# CORS (for API access)
CORS_ALLOWED_ORIGINS=http://localhost:3000

# Email
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=mailhog
EMAIL_PORT=1025

Project Scoping

All data is scoped to projects. Users only see data from projects they're assigned to. Superadmins bypass scoping.

This is enforced at the API level (Django) and transparent to the frontend (React).

Contributing

Each repository has its own contribution guidelines:

• api/: See api/README.md
• spa/: See spa/README.md
• orchestrator: This file

License

MIT

Credits

• Original Laravel/Vue/Inertia version: devvir/mtav
• Django/React decoupled version: Created for learning and experimentation