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 21:11: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/memory-bank/systemPatterns.md
+++ b/shared/docs/memory-bank/systemPatterns.md
@@ -0,0 +1,197 @@
+# System Patterns
+
+## Architectural Patterns
+
+### MVT Implementation
+1. Models
+   - Use abstract base classes for common fields
+   - Implement custom model managers for complex queries
+   - Define clear relationships and constraints
+   - Include field-level validation
+
+2. Views
+   - Prefer class-based views
+   - Use mixins for shared functionality
+   - Implement proper permission checks
+   - Handle HTMX requests explicitly
+
+3. Templates
+   - Maintain hierarchy with base templates
+   - Use partial templates for HTMX responses
+   - Implement component-based structure
+   - Follow progressive enhancement
+
+## Design Patterns
+
+### Data Access
+1. Query Patterns
+   - Use select_related() for foreign keys
+   - Implement prefetch_related() for reverse relationships
+   - Create custom model managers
+   - Optimize database queries
+
+2. Caching Strategy
+   - Cache template fragments
+   - Implement model-level caching
+   - Use Redis for session storage
+   - Cache invalidation rules
+
+### Historical Tracking
+- All model changes create immutable pghistory events
+- Events contain:
+  - Full object state snapshot
+  - Contextual metadata (user, request fingerprint)
+  - Semantic event label (created, updated, deleted)
+- Middleware integration:
+  ```python
+  # core/middleware.py
+  pghistory.context(lambda request: {
+      'user': str(request.user) if request.user.is_authenticated else None,
+      'ip': request.META.get('REMOTE_ADDR'),
+      'user_agent': request.META.get('HTTP_USER_AGENT')
+  })
+  ```
+
+## Frontend Patterns
+
+1. HTMX Integration
+   ```html
+   <!-- Partial Update Pattern -->
+   <div hx-get="/endpoint"
+        hx-trigger="event"
+        hx-target="#target">
+   ```
+
+2. AlpineJS Components
+   ```html
+   <!-- State Management Pattern -->
+   <div x-data="{ state: {} }"
+        x-init="state = await fetchData()">
+   ```
+
+3. Tailwind Components
+   ```html
+   <!-- Component Structure -->
+   <div class="component-wrapper">
+      <div class="component-header"></div>
+      <div class="component-content"></div>
+   </div>
+   ```
+
+## Authentication Patterns
+
+### User Management
+1. Custom User Model
+   - Extended user profiles
+   - Role-based permissions
+   - Activity tracking
+   - Profile customization
+
+2. Authentication Flow
+   - Login/registration process
+   - Password reset workflow
+   - Email verification
+   - Session management
+
+## Content Management
+
+### Moderation Flow
+1. Submission Process
+   - Content validation
+   - Automatic checks
+   - Manual review queue
+   - Approval workflow
+
+2. Review System
+   - Rating framework
+   - Media handling
+   - User verification
+   - Content filtering
+
+## Error Handling
+
+### Backend Errors
+1. Exception Handling
+   ```python
+   try:
+       # Operation
+   except SpecificException as e:
+       # Specific handling
+   except Exception as e:
+       # Generic handling
+   ```
+
+2. Response Patterns
+   ```python
+   # Success Response
+   return JsonResponse({'status': 'success', 'data': data})
+   
+   # Error Response
+   return JsonResponse({'status': 'error', 'message': str(e)})
+   ```
+
+### Frontend Errors
+1. User Feedback
+   - Toast notifications
+   - Inline validation
+   - Form feedback
+   - Error states
+
+## Testing Patterns
+
+### Unit Tests
+```python
+class ModelTests(TestCase):
+    def setUp(self):
+        # Test setup
+        
+    def test_specific_functionality(self):
+        # Test implementation
+```
+
+### Integration Tests
+```python
+class ViewTests(TestCase):
+    def setUp(self):
+        self.client = Client()
+        
+    def test_view_functionality(self):
+        # Test implementation
+```
+
+## Development Workflows
+
+### Package Management
+IMPORTANT: When adding Python packages to the project, only use UV:
+```bash
+uv add <package>
+```
+Do not attempt to install packages using any other method (pip, poetry, etc.).
+
+### Development Server Management
+Server Startup Process
+IMPORTANT: Always execute the following command exactly as shown to start the development server:
+```bash
+lsof -ti :8000 | xargs kill -9; find . -type d -name "__pycache__" -exec rm -r {} +; uv run manage.py tailwind runserver
+```
+
+Note: These steps must be executed in this exact order as a single command to ensure consistent behavior.
+
+### Feature Development
+1. Planning
+   - Technical specification
+   - Component design
+   - Database schema
+   - API endpoints
+
+2. Implementation
+   - Model creation
+   - View implementation
+   - Template design
+   - Testing coverage
+
+3. Review Process
+   - Code review
+   - Testing verification
+   - Documentation update
+   - Deployment planning