pacnpal/thrillwiki_django_no_react
1
1
Fork 0
mirror of https://github.com/pacnpal/thrillwiki_django_no_react.git synced 2025-12-20 10:11:09 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
6391b3d81cbec9c3e2f19842fbef762c98f4dc5d
thrillwiki_django_no_react/architecture/monorepo-structure-plan.md
pacnpal d504d41de2 feat: complete monorepo structure with frontend and shared resources 
- Add complete backend/ directory with full Django application
- Add frontend/ directory with Vite + TypeScript setup ready for Next.js
- Add comprehensive shared/ directory with:
  - Complete documentation and memory-bank archives
  - Media files and avatars (letters, park/ride images)
  - Deployment scripts and automation tools
  - Shared types and utilities
- Add architecture/ directory with migration guides
- Configure pnpm workspace for monorepo development
- Update .gitignore to exclude .django_tailwind_cli/ build artifacts
- Preserve all historical documentation in shared/docs/memory-bank/
- Set up proper structure for full-stack development with shared resources
2025-08-23 18:40:07 -04:00

525 lines
17 KiB
Markdown
Raw Blame History

# ThrillWiki Django + Vue.js Monorepo Architecture Plan
## Executive Summary
This document outlines the optimal monorepo directory structure for migrating the ThrillWiki Django project to a Django + Vue.js architecture. The design separates backend and frontend concerns while maintaining existing Django app organization and supporting modern development workflows.
## Current Project Analysis
### Django Apps Structure
- **accounts**: User management and authentication
- **parks**: Theme park data and operations
- **rides**: Ride information and management
- **moderation**: Content moderation system
- **location**: Geographic data handling
- **media**: File and image management
- **email_service**: Email functionality
- **core**: Core utilities and services
### Key Infrastructure
- **Package Management**: UV-based Python setup
- **Configuration**: `config/django/` for settings, `config/settings/` for modular settings
- **Development**: `scripts/dev_server.sh` with comprehensive setup
- **Static Assets**: Tailwind CSS integration, `static/` and `staticfiles/`
- **Media Handling**: Organized `media/` directory with park/ride subdirectories
## Proposed Monorepo Structure
```
thrillwiki-monorepo/
├── README.md
├── pyproject.toml # Python dependencies (backend only)
├── package.json # Node.js dependencies (monorepo coordination)
├── pnpm-workspace.yaml # pnpm workspace configuration
├── .env.example
├── .gitignore
├──
├── backend/ # Django Backend
│ ├── manage.py
│ ├── pyproject.toml # Backend-specific dependencies
│ ├── config/
│ │ ├── django/
│ │ │ ├── base.py
│ │ │ ├── local.py
│ │ │ ├── production.py
│ │ │ └── test.py
│ │ └── settings/
│ │ ├── database.py
│ │ ├── email.py
│ │ └── security.py
│ ├── thrillwiki/
│ │ ├── __init__.py
│ │ ├── urls.py
│ │ ├── wsgi.py
│ │ ├── asgi.py
│ │ └── views.py
│ ├── apps/ # Django apps
│ │ ├── accounts/
│ │ ├── parks/
│ │ ├── rides/
│ │ ├── moderation/
│ │ ├── location/
│ │ ├── media/
│ │ ├── email_service/
│ │ └── core/
│ ├── templates/ # Django templates (API responses, admin)
│ ├── static/ # Backend static files
│ │ └── admin/ # Django admin assets
│ ├── media/ # User uploads
│ │ ├── avatars/
│ │ ├── park/
│ │ └── submissions/
│ └── tests/ # Backend tests
│
├── frontend/ # Vue.js Frontend
│ ├── package.json
│ ├── pnpm-lock.yaml
│ ├── vite.config.js
│ ├── tailwind.config.js
│ ├── index.html
│ ├── src/
│ │ ├── main.js
│ │ ├── App.vue
│ │ ├── router/
│ │ │ └── index.js
│ │ ├── stores/ # Pinia/Vuex stores
│ │ │ ├── auth.js
│ │ │ ├── parks.js
│ │ │ └── rides.js
│ │ ├── components/
│ │ │ ├── common/ # Shared components
│ │ │ ├── parks/ # Park-specific components
│ │ │ ├── rides/ # Ride-specific components
│ │ │ └── moderation/ # Moderation components
│ │ ├── views/ # Page components
│ │ │ ├── Home.vue
│ │ │ ├── parks/
│ │ │ ├── rides/
│ │ │ └── auth/
│ │ ├── composables/ # Vue 3 composables
│ │ │ ├── useAuth.js
│ │ │ ├── useApi.js
│ │ │ └── useTheme.js
│ │ ├── services/ # API service layer
│ │ │ ├── api.js
│ │ │ ├── auth.js
│ │ │ ├── parks.js
│ │ │ └── rides.js
│ │ ├── assets/
│ │ │ ├── images/
│ │ │ └── styles/
│ │ │ ├── globals.css
│ │ │ └── components/
│ │ └── utils/
│ ├── public/
│ │ ├── favicon.ico
│ │ └── images/
│ ├── dist/ # Build output
│ └── tests/ # Frontend tests
│ ├── unit/
│ └── e2e/
│
├── shared/ # Shared Resources
│ ├── docs/ # Documentation
│ │ ├── api/ # API documentation
│ │ ├── deployment/ # Deployment guides
│ │ └── development/ # Development setup
│ ├── scripts/ # Build and deployment scripts
│ │ ├── dev/
│ │ │ ├── start-backend.sh
│ │ │ ├── start-frontend.sh
│ │ │ └── start-full-stack.sh
│ │ ├── build/
│ │ │ ├── build-frontend.sh
│ │ │ └── build-production.sh
│ │ ├── deploy/
│ │ └── utils/
│ ├── config/ # Shared configuration
│ │ ├── docker/
│ │ │ ├── Dockerfile.backend
│ │ │ ├── Dockerfile.frontend
│ │ │ └── docker-compose.yml
│ │ ├── nginx/
│ │ └── ci/ # CI/CD configuration
│ │ └── github-actions/
│ └── types/ # Shared TypeScript types
│ ├── api.ts
│ ├── parks.ts
│ └── rides.ts
│
├── logs/ # Application logs
├── backups/ # Database backups
├── uploads/ # Temporary upload directory
└── dist/ # Production build output
├── backend/ # Django static files
└── frontend/ # Vue.js build
```
## Directory Organization Rationale
### 1. Clear Separation of Concerns
- **backend/**: Contains all Django-related code, maintaining existing app structure
- **frontend/**: Vue.js application with modern structure (Vite + Vue 3)
- **shared/**: Common resources, documentation, and configuration
### 2. Backend Structure (`backend/`)
- Preserves existing Django app organization under `apps/`
- Maintains UV-based Python dependency management
- Keeps configuration structure with `config/django/` and `config/settings/`
- Separates templates for API responses vs. frontend UI
### 3. Frontend Structure (`frontend/`)
- Modern Vue 3 + Vite setup with TypeScript support
- Organized by feature areas (parks, rides, auth)
- Composables for Vue 3 Composition API patterns
- Service layer for API communication with Django backend
- Tailwind CSS integration with shared design system
### 4. Shared Resources (`shared/`)
- Centralized documentation and deployment scripts
- Docker configuration for containerized deployment
- TypeScript type definitions shared between frontend and API
- CI/CD pipeline configuration
## Static File Strategy
### Development
```mermaid
graph LR
A[Vue Dev Server :3000] --> B[Vite HMR]
C[Django Dev Server :8000] --> D[Django Static Files]
E[Tailwind CSS] --> F[Both Frontend & Backend]
```
### Production
```mermaid
graph LR
A[Vue Build] --> B[dist/frontend/]
C[Django Collectstatic] --> D[dist/backend/]
E[Nginx] --> F[Serves Both]
F --> G[Frontend Assets]
F --> H[API Endpoints]
F --> I[Media Files]
```
### Implementation Details
1. **Development Mode**:
- Frontend: Vite dev server on port 3000 with HMR
- Backend: Django dev server on port 8000
- Proxy API calls from frontend to backend
2. **Production Mode**:
- Frontend built to `dist/frontend/`
- Django static files collected to `dist/backend/`
- Nginx serves static files and proxies API calls
## Media File Management
### Current Structure Preservation
```
media/
├── avatars/ # User profile images
├── park/ # Park-specific media
│ ├── {park-slug}/
│ │ └── {ride-slug}/
└── submissions/ # User-submitted content
└── photos/
```
### Strategy
- **Development**: Django serves media files directly
- **Production**: CDN or object storage (S3/CloudFlare) integration
- **Frontend Access**: Media URLs provided via API responses
- **Upload Handling**: Django handles all file uploads, Vue.js provides UI
## Development Workflow Integration
### Package Management
- **Root**: Node.js dependencies for frontend and tooling (using pnpm)
- **Backend**: UV for Python dependencies (existing approach)
- **Frontend**: pnpm for Vue.js dependencies
### Development Scripts
```bash
# Root level scripts
pnpm run dev # Start both backend and frontend
pnpm run dev:backend # Start only Django
pnpm run dev:frontend # Start only Vue.js
pnpm run build # Build for production
pnpm run test # Run all tests
# Backend specific (using UV)
cd backend && uv run manage.py runserver
cd backend && uv run manage.py test
# Frontend specific
cd frontend && pnpm run dev
cd frontend && pnpm run build
cd frontend && pnpm run test
```
### Environment Configuration
```bash
# Root .env (shared settings)
DATABASE_URL=
REDIS_URL=
SECRET_KEY=
# Backend .env (Django specific)
DJANGO_SETTINGS_MODULE=config.django.local
DEBUG=True
# Frontend .env (Vue specific)
VITE_API_BASE_URL=http://localhost:8000/api
VITE_APP_TITLE=ThrillWiki
```
### Package Manager Configuration
#### Root pnpm-workspace.yaml
```yaml
packages:
- 'frontend'
# Backend is managed separately with uv
```
#### Root package.json
```json
{
"name": "thrillwiki-monorepo",
"private": true,
"packageManager": "pnpm@9.0.0",
"scripts": {
"dev": "concurrently \"pnpm run dev:backend\" \"pnpm run dev:frontend\"",
"dev:backend": "cd backend && uv run manage.py runserver",
"dev:frontend": "cd frontend && pnpm run dev",
"build": "pnpm run build:frontend && cd backend && uv run manage.py collectstatic --noinput",
"build:frontend": "cd frontend && pnpm run build",
"test": "pnpm run test:backend && pnpm run test:frontend",
"test:backend": "cd backend && uv run manage.py test",
"test:frontend": "cd frontend && pnpm run test",
"lint": "cd frontend && pnpm run lint && cd ../backend && uv run flake8 .",
"format": "cd frontend && pnpm run format && cd ../backend && uv run black ."
},
"devDependencies": {
"concurrently": "^8.2.0"
}
}
```
#### Frontend package.json
```json
{
"name": "thrillwiki-frontend",
"private": true,
"version": "0.1.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview",
"test": "vitest",
"test:e2e": "playwright test",
"lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix",
"format": "prettier --write src/",
"type-check": "vue-tsc --noEmit"
},
"dependencies": {
"vue": "^3.4.0",
"vue-router": "^4.3.0",
"pinia": "^2.1.0",
"axios": "^1.6.0"
},
"devDependencies": {
"@vitejs/plugin-vue": "^5.0.0",
"vite": "^5.0.0",
"vue-tsc": "^2.0.0",
"typescript": "^5.3.0",
"tailwindcss": "^3.4.0",
"autoprefixer": "^10.4.0",
"postcss": "^8.4.0",
"eslint": "^8.57.0",
"prettier": "^3.2.0",
"vitest": "^1.3.0",
"@playwright/test": "^1.42.0"
}
}
```
## File Migration Mapping
### High-Level Moves
```
Current → New Location
├── manage.py → backend/manage.py
├── pyproject.toml → backend/pyproject.toml (+ root package.json)
├── config/ → backend/config/
├── thrillwiki/ → backend/thrillwiki/
├── accounts/ → backend/apps/accounts/
├── parks/ → backend/apps/parks/
├── rides/ → backend/apps/rides/
├── moderation/ → backend/apps/moderation/
├── location/ → backend/apps/location/
├── media/ → backend/apps/media/
├── email_service/ → backend/apps/email_service/
├── core/ → backend/apps/core/
├── templates/ → backend/templates/ (API) + frontend/src/views/ (UI)
├── static/ → backend/static/ (admin) + frontend/src/assets/
├── media/ → media/ (shared, accessible to both)
├── scripts/ → shared/scripts/
├── docs/ → shared/docs/
├── tests/ → backend/tests/ + frontend/tests/
└── staticfiles/ → dist/backend/ (generated)
```
### Detailed Backend App Moves
Each Django app moves to `backend/apps/{app_name}/` with structure preserved:
- Models, views, serializers stay the same
- Templates for API responses remain in app directories
- Static files move to frontend if UI-related
- Tests remain with respective apps
## Build and Deployment Strategy
### Development Build Process
1. **Backend**: No build step, runs directly with Django dev server
2. **Frontend**: Vite development server with HMR
3. **Shared**: Scripts orchestrate starting both services
### Production Build Process
```mermaid
graph TD
A[CI/CD Trigger] --> B[Install Dependencies]
B --> C[Build Frontend]
B --> D[Collect Django Static]
C --> E[Generate Frontend Bundle]
D --> F[Collect Backend Assets]
E --> G[Create Docker Images]
F --> G
G --> H[Deploy to Production]
```
### Container Strategy
- **Multi-stage Docker builds**: Separate backend and frontend images
- **Nginx**: Reverse proxy and static file serving
- **Volume mounts**: For media files and logs
- **Environment-based configuration**: Development vs. production
## API Integration Strategy
### Backend API Structure
```python
# Enhanced DRF setup for SPA
REST_FRAMEWORK = {
'DEFAULT_RENDERER_CLASSES': [
'rest_framework.renderers.JSONRenderer',
],
'DEFAULT_AUTHENTICATION_CLASSES': [
'rest_framework.authentication.SessionAuthentication',
'rest_framework.authentication.TokenAuthentication',
],
}
# CORS for development
CORS_ALLOWED_ORIGINS = [
"http://localhost:3000", # Vue dev server
]
```
### Frontend API Service
```javascript
// API service with auth integration
class ApiService {
constructor() {
this.client = axios.create({
baseURL: import.meta.env.VITE_API_BASE_URL,
withCredentials: true,
});
}
// Park operations
getParks(params = {}) {
return this.client.get('/parks/', { params });
}
// Ride operations
getRides(parkId, params = {}) {
return this.client.get(`/parks/${parkId}/rides/`, { params });
}
}
```
## Configuration Management
### Shared Environment Variables
- Database connections
- Redis/Cache settings
- Secret keys and API keys
- Feature flags
### Application-Specific Settings
- **Django**: `backend/config/django/`
- **Vue.js**: `frontend/.env` files
- **Docker**: `shared/config/docker/`
### Development vs. Production
- Development: Multiple local servers, hot reloading
- Production: Containerized deployment, CDN integration
## Benefits of This Structure
1. **Clear Separation**: Backend and frontend concerns are clearly separated
2. **Scalability**: Each part can be developed, tested, and deployed independently
3. **Modern Workflow**: Supports latest Vue 3, Vite, and Django patterns
4. **Backward Compatibility**: Preserves existing Django app structure
5. **Developer Experience**: Hot reloading, TypeScript support, modern tooling
6. **Deployment Flexibility**: Can deploy as SPA + API or traditional Django
## Implementation Phases
### Phase 1: Structure Setup
1. Create new directory structure
2. Move Django code to `backend/`
3. Initialize Vue.js frontend
4. Set up basic API integration
### Phase 2: Frontend Development
1. Create Vue.js components for existing Django templates
2. Implement routing and state management
3. Integrate with Django API endpoints
4. Add authentication flow
### Phase 3: Build & Deploy
1. Set up build processes
2. Configure CI/CD pipelines
3. Implement production deployment
4. Performance optimization
## Considerations and Trade-offs
### Advantages
- Modern development experience
- Better code organization
- Independent scaling
- Rich frontend interactions
- API-first architecture
### Challenges
- Increased complexity
- Build process coordination
- Authentication across services
- SEO considerations (if needed)
- Development environment setup
## Next Steps
1. **Validate Architecture**: Review with development team
2. **Prototype Setup**: Create basic structure with sample components
3. **Migration Planning**: Detailed plan for moving existing code
4. **Tool Selection**: Finalize Vue.js ecosystem choices (Pinia vs. Vuex, etc.)
5. **Implementation**: Begin phase-by-phase migration
---
This architecture provides a solid foundation for migrating ThrillWiki to a modern Django + Vue.js monorepo while preserving existing functionality and enabling future growth.
Reference in New Issue View Git Blame Copy Permalink