Skip to content

QUICKSTART.md

Latest commit

 

History

History
324 lines (240 loc) · 6.87 KB

QUICKSTART.md

File metadata and controls

324 lines (240 loc) · 6.87 KB

MTAV Stack - Quick Start Guide

✅ What You Have Now

A 3-repository architecture that decouples backend and frontend:

mtav-stack/                    # Orchestrator repository
├── api/                       # Backend submodule (Django REST API)
├── spa/                       # Frontend submodule (React SPA)
├── mtav                       # Unified development script
├── docker-compose.yml         # Service orchestration
├── README.md                  # Overview
└── ARCHITECTURE.md            # Detailed architecture guide

Repository Status

✅ api/ - Git repo initialized (commit: 1a9d097) ✅ spa/ - Git repo initialized (commit: 0bf0dbb) ✅ mtav-stack/ - Git repo initialized with submodules (commit: 7882451)

🚀 How to Use

First Time Setup

cd /home/x/Development/Repos/MTAV/mtav/mtav-stack

# Start everything
./mtav up

This will:

  1. Create .env from .env.example
  2. Build Docker images for backend and frontend
  3. Start all services (db, redis, backend, frontend, celery, mailhog)
  4. Run database migrations
  5. Install dependencies

Access Points

Once running:

Daily Development

# Start
./mtav up

# View logs
./mtav logs

# Run backend command
./mtav backend migrate
./mtav backend createsuperuser

# Run frontend command
./mtav frontend install
./mtav frontend build

# Shell access
./mtav shell backend
./mtav shell frontend

# Run tests
./mtav test              # All tests
./mtav test-backend      # Django tests
./mtav test-frontend     # React tests

# Stop
./mtav down

🔄 Swapping Components

Swap Backend (Example: Django → Rails)

# 1. Remove Django submodule
git submodule deinit api
git rm api

# 2. Create/clone your Rails API (implementing same REST contract)
# 3. Add as submodule
git submodule add [your-rails-api-url] api

# 4. Update docker-compose.yml if needed
# 5. Rebuild
./mtav rebuild backend

# 6. Done! Frontend works unchanged
./mtav up

Swap Frontend (Example: React → Vue)

# 1. Remove React submodule
git submodule deinit spa
git rm spa

# 2. Create/clone your Vue SPA (consuming same REST API)
# 3. Add as submodule
git submodule add [your-vue-spa-url] spa

# 4. Rebuild
./mtav rebuild frontend

# 5. Done! Backend works unchanged
./mtav up

📝 Development Workflow

Working on Backend

cd api/

# Make changes
# Run tests: pytest
# Commit and push

git add .
git commit -m "Add feature"
git push

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

Working on Frontend

cd spa/

# Make changes
# Run tests: npm test
# Commit and push

git add .
git commit -m "Add component"
git push

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

🎯 Next Steps

For Learning Different Backends

Create alternative backends that implement the same REST contract:

  1. Rails API

    rails new mtav-rails-api --api
# Implement same endpoints: /api/auth/*, /api/families/, etc.
# Same JWT authentication
# Same project scoping logic

  2. Laravel API (without Inertia)

    laravel new mtav-laravel-api
# Install Laravel Sanctum for JWT
# Implement same REST endpoints

  3. FastAPI

    # Python alternative to Django
# Implement same contract

Then swap: git submodule deinit api && git submodule add [new-api] api

For Learning Different Frontends

Create alternative frontends that consume the same API:

  1. Vue SPA

    npm create vue@latest mtav-vue-spa
# Install axios for API calls
# Implement same pages/features
# Point to same API: http://localhost:8000

  2. Svelte SPA

    npm create svelte@latest mtav-svelte-spa
# Same approach

Then swap: git submodule deinit spa && git submodule add [new-spa] spa

📚 Documentation

  • Main README: README.md - Overview and quick start
  • Architecture Guide: ARCHITECTURE.md - Detailed explanation of multi-repo pattern
  • Backend README: api/README.md - Django API specifics
  • Frontend README: spa/README.md - React SPA specifics

🧪 Testing the Setup

# 1. Start everything
./mtav up

# 2. Create superuser
./mtav backend createsuperuser

# 3. Open frontend
open http://localhost:3000

# 4. Login with superuser credentials

# 5. Verify API works
curl http://localhost:8000/api/projects/

# 6. Check tests
./mtav test

🔧 Troubleshooting

Submodules not showing up?

git submodule update --init --recursive

Permission denied on ./mtav?

chmod +x mtav

Docker issues?

./mtav down
./mtav fresh  # Nuclear option: rebuild everything

Frontend can't connect to backend?

Check .env has: VITE_API_URL=http://localhost:8000

🎓 Learning Path

  1. Week 1: Understand current Django + React setup

    • Explore api/ code
    • Explore spa/ code
    • Run tests, make small changes

  2. Week 2: Try swapping frontend

    • Create Vue version of one page
    • Consume same API endpoints
    • Compare React vs Vue

  3. Week 3: Try swapping backend

    • Create Rails version of one endpoint
    • Implement same response format
    • Compare Django vs Rails

  4. Week 4: Mix and match

    • Try Rails + React
    • Try Django + Vue
    • Understand the power of REST contracts

📦 Pushing to GitHub

When ready to push to GitHub:

# 1. Create 3 repos on GitHub:
#    - yourusername/mtav-api
#    - yourusername/mtav-spa
#    - yourusername/mtav-stack

# 2. Push backend
cd api/
git remote add origin https://github.com/yourusername/mtav-api.git
git push -u origin main

# 3. Push frontend
cd ../spa/
git remote add origin https://github.com/yourusername/mtav-spa.git
git push -u origin main

# 4. Update orchestrator .gitmodules
cd ..
# Edit .gitmodules to use GitHub URLs instead of ./api and ./spa

# 5. Push orchestrator
git add .gitmodules
git commit -m "Update submodule URLs for GitHub"
git remote add origin https://github.com/yourusername/mtav-stack.git
git push -u origin main

🎉 Summary

You now have a fully decoupled Django + React application that:

✅ Works exactly like the Laravel/Inertia version (from user perspective) ✅ Can swap backend independently (Django → Rails → Laravel → FastAPI) ✅ Can swap frontend independently (React → Vue → Svelte → Angular) ✅ Has unified development experience via ./mtav script ✅ Uses Docker for portability ✅ Has comprehensive tests ✅ Is properly structured with 3 git repositories

Perfect for learning multiple frameworks while maintaining the same familiar domain model!