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-12-20 08:31:08 -05:00 · 2025-08-23 18:40:07 -04:00
parent b0e0678590
commit d504d41de2
762 changed files with 142636 additions and 0 deletions
--- a/shared/docs/DEVELOPMENT_SETUP.md
+++ b/shared/docs/DEVELOPMENT_SETUP.md
@@ -0,0 +1,219 @@
+# ThrillWiki Development Setup
+
+This guide explains how to run the ThrillWiki project without requiring the `scripts/dev_server.sh` shell script.
+
+## Quick Start (Recommended)
+
+The easiest way to get started is using the new Django management commands:
+
+```bash
+# One-time setup and run the server
+python manage.py rundev
+
+# Or just set up the environment (without starting the server)
+python manage.py setup_dev
+
+# Then run the server separately
+python manage.py runserver
+```
+
+## Manual Setup
+
+If you prefer to set things up manually or customize your environment:
+
+### 1. Environment Variables
+
+Copy the provided `.env` file or create your own:
+
+```bash
+cp .env.example .env
+# Edit .env with your specific configuration
+```
+
+The `.env` file should contain all necessary environment variables. Key variables include:
+
+```env
+# Django settings
+DJANGO_SETTINGS_MODULE=config.django.local
+DEBUG=True
+SECRET_KEY=your-secret-key-here
+
+# Database (PostgreSQL with PostGIS required)
+DATABASE_URL=postgis://username:password@localhost:5432/database_name
+
+# GeoDjango library paths (adjust for your system)
+GDAL_LIBRARY_PATH=/opt/homebrew/lib/libgdal.dylib  # macOS with Homebrew
+GEOS_LIBRARY_PATH=/opt/homebrew/lib/libgeos_c.dylib
+
+# For Linux:
+# GDAL_LIBRARY_PATH=/usr/lib/libgdal.so
+# GEOS_LIBRARY_PATH=/usr/lib/libgeos_c.so
+```
+
+### 2. Virtual Environment (Recommended)
+
+```bash
+# Create and activate virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Linux/macOS
+# or
+.venv\\Scripts\\activate  # Windows
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### 3. Database Setup
+
+Make sure you have PostgreSQL with PostGIS extension installed and running:
+
+```bash
+# Create database and user (adjust as needed)
+createdb thrillwiki_test_db
+psql -d thrillwiki_test_db -c "CREATE EXTENSION postgis;"
+
+# Run migrations
+python manage.py migrate
+```
+
+### 4. Static Files and Assets
+
+```bash
+# Create necessary directories
+mkdir -p logs profiles media staticfiles static/css
+
+# Collect static files
+python manage.py collectstatic --noinput
+
+# Build Tailwind CSS (if you have npm installed)
+python manage.py tailwind build
+```
+
+### 5. Create Superuser
+
+```bash
+python manage.py createsuperuser
+# or use the predefined admin/admin user:
+python manage.py shell -c "
+from django.contrib.auth import get_user_model
+User = get_user_model()
+if not User.objects.filter(username='admin').exists():
+    User.objects.create_superuser('admin', 'admin@example.com', 'admin')
+"
+```
+
+### 6. Run the Server
+
+```bash
+python manage.py runserver
+# or if you have django-extensions installed:
+python manage.py runserver_plus
+```
+
+## Available Management Commands
+
+The project now includes several helpful management commands:
+
+### `rundev`
+Automatically sets up the development environment and starts the server:
+
+```bash
+# Full setup and start server
+python manage.py rundev
+
+# Skip setup, just start server
+python manage.py rundev --skip-setup
+
+# Use different port
+python manage.py rundev --port 8080
+
+# Use runserver_plus if available
+python manage.py rundev --use-runserver-plus
+```
+
+### `setup_dev`
+Sets up the development environment without starting the server:
+
+```bash
+# Full setup
+python manage.py setup_dev
+
+# Skip specific steps
+python manage.py setup_dev --skip-migrations
+python manage.py setup_dev --skip-static
+python manage.py setup_dev --skip-tailwind
+python manage.py setup_dev --skip-superuser
+```
+
+## Environment Configuration
+
+The project supports multiple environments through different settings modules:
+
+- **Local Development**: `config.django.local` (default)
+- **Production**: `config.django.production` 
+- **Testing**: `config.django.test`
+
+### Environment Auto-Detection
+
+The `manage.py` script automatically detects the appropriate environment based on:
+
+1. Existing `DJANGO_SETTINGS_MODULE` environment variable
+2. Command line arguments (`test` command)
+3. Production environment indicators (Heroku, AWS, Kubernetes, etc.)
+4. `DEBUG` environment variable setting
+
+### Manual Environment Override
+
+You can override environment detection by setting the `DJANGO_SETTINGS_MODULE` environment variable:
+
+```bash
+export DJANGO_SETTINGS_MODULE=config.django.production
+python manage.py runserver
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **ImportError: Couldn't import Django**
+   - Make sure Django is installed: `pip install django`
+   - Check that your virtual environment is activated
+   - Try: `python manage.py setup_dev`
+
+2. **Database connection errors**
+   - Verify PostgreSQL is running
+   - Check your `DATABASE_URL` in `.env`
+   - Ensure PostGIS extension is installed: `CREATE EXTENSION postgis;`
+
+3. **GeoDjango library path errors**
+   - Update `GDAL_LIBRARY_PATH` and `GEOS_LIBRARY_PATH` in `.env`
+   - For macOS with Homebrew: `/opt/homebrew/lib/libgdal.dylib`
+   - For Linux: `/usr/lib/libgdal.so` or `/usr/lib/x86_64-linux-gnu/libgdal.so`
+
+4. **Static files not loading**
+   - Run: `python manage.py collectstatic`
+   - For development, ensure `DEBUG=True` in your `.env`
+
+5. **Tailwind CSS not building**
+   - Install Node.js and npm
+   - Run: `python manage.py tailwind build`
+
+### Getting Help
+
+- Check the logs in the `logs/` directory
+- Use Django's built-in error pages when `DEBUG=True`
+- Run system checks: `python manage.py check`
+
+## Comparison with dev_server.sh
+
+The new setup provides the same functionality as the original `scripts/dev_server.sh` but with more flexibility:
+
+| Feature | dev_server.sh | New Setup |
+|---------|---------------|-----------|
+| Environment variables | Hard-coded in script | Configurable via `.env` |
+| Setup steps | All-or-nothing | Selective with flags |
+| Cross-platform | bash-only | Python (cross-platform) |
+| Customization | Edit script | Command arguments |
+| Integration | External script | Django management commands |
+
+You can still use the original script if preferred, but the new approach provides better integration with Django's ecosystem and more flexibility for different development workflows.