From ac8fa2ae9ca51e4e23bad5fd87d539dce5ec64d3 Mon Sep 17 00:00:00 2001 From: "IGNY8 VPS (Salman)" Date: Sat, 29 Nov 2025 15:28:20 +0000 Subject: [PATCH] master ref --- docs/MASTER_REFERENCE.md | 598 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 598 insertions(+) diff --git a/docs/MASTER_REFERENCE.md b/docs/MASTER_REFERENCE.md index f4255bf6..66726ce2 100644 --- a/docs/MASTER_REFERENCE.md +++ b/docs/MASTER_REFERENCE.md @@ -1349,6 +1349,604 @@ WordPress >= 5.0 --- +## Portable Package Structure + +This section defines the **essential files and folders** needed to deploy IGNY8 to a new infrastructure with the same tech stack. These are IGNY8-specific application files (excluding standard framework boilerplate that gets installed via package managers). + +### Backend Essential Package Tree + +**Package Only These Files** - Excludes Django-generated boilerplate and dependencies installed via pip: + +``` +backend/ +├── manage.py # Django entry point (IGNY8-configured) +├── requirements.txt # Python dependencies (essential) +├── Dockerfile # Container configuration (essential) +│ +└── igny8_core/ # Main Django project + ├── __init__.py # Project marker + ├── settings.py # ⭐ IGNY8 configuration (critical) + ├── test_settings.py # Test configuration + ├── urls.py # Main URL routing (IGNY8-specific) + ├── asgi.py # ASGI entry point + ├── wsgi.py # WSGI entry point + ├── celery.py # ⭐ Celery configuration (critical) + │ + ├── admin/ # Custom Django admin + │ ├── __init__.py + │ ├── apps.py + │ ├── base.py # Admin base classes + │ └── site.py # Custom admin site + │ + ├── auth/ # ⭐ Authentication module (critical) + │ ├── __init__.py + │ ├── apps.py + │ ├── admin.py + │ ├── models.py # User, Account, Site models + │ ├── serializers.py + │ ├── views.py + │ ├── urls.py + │ ├── permissions.py + │ ├── middleware.py # Account context middleware + │ ├── utils.py + │ └── management/ + │ └── commands/ # Custom management commands + │ + ├── ai/ # ⭐ AI Framework (critical) + │ ├── __init__.py + │ ├── apps.py + │ ├── admin.py + │ ├── models.py # AIJob, AITaskResult + │ ├── base.py # Base AI classes + │ ├── ai_core.py # Core AI logic + │ ├── engine.py # AI execution engine + │ ├── registry.py # AI function registry + │ ├── prompts.py # AI prompt templates + │ ├── validators.py + │ ├── tracker.py # Progress tracking + │ ├── tasks.py # Celery tasks + │ ├── settings.py # AI configuration + │ ├── constants.py + │ ├── functions/ # AI function implementations + │ │ ├── __init__.py + │ │ ├── base.py + │ │ ├── content_generation.py + │ │ ├── image_generation.py + │ │ └── ... + │ ├── migrations/ # Database migrations (critical) + │ └── tests/ + │ + ├── api/ # ⭐ API Infrastructure (critical) + │ ├── __init__.py + │ ├── base.py # Base ViewSet classes + │ ├── response.py # Unified response format + │ ├── pagination.py # Pagination classes + │ ├── permissions.py # API permissions + │ ├── authentication.py # JWT authentication + │ ├── throttles.py # Rate limiting + │ ├── exception_handlers.py # Error handling + │ ├── schema_extensions.py # OpenAPI schema + │ ├── wordpress_publishing.py # WordPress integration + │ └── tests/ + │ + ├── business/ # ⭐ Business Logic Layer (critical) + │ ├── __init__.py + │ ├── planning/ + │ │ ├── __init__.py + │ │ ├── cluster_service.py + │ │ ├── keyword_service.py + │ │ └── idea_service.py + │ ├── content/ + │ │ ├── __init__.py + │ │ ├── generation_service.py + │ │ └── image_service.py + │ ├── linking/ + │ │ ├── __init__.py + │ │ └── linking_service.py + │ ├── optimization/ + │ │ ├── __init__.py + │ │ └── optimization_service.py + │ ├── publishing/ + │ │ ├── __init__.py + │ │ └── wordpress_service.py + │ ├── site_building/ + │ │ ├── __init__.py + │ │ └── builder_service.py + │ ├── automation/ + │ │ ├── __init__.py + │ │ └── automation_service.py + │ ├── integration/ + │ │ ├── __init__.py + │ │ └── integration_service.py + │ └── billing/ + │ ├── __init__.py + │ └── credit_service.py + │ + ├── modules/ # ⭐ Feature Modules (critical) + │ ├── __init__.py + │ │ + │ ├── planner/ # Keyword planning + │ │ ├── __init__.py + │ │ ├── apps.py + │ │ ├── admin.py + │ │ ├── models.py + │ │ ├── serializers.py + │ │ ├── cluster_serializers.py + │ │ ├── views.py + │ │ ├── urls.py + │ │ ├── migrations/ + │ │ └── management/ + │ │ + │ ├── writer/ # Content generation + │ │ ├── __init__.py + │ │ ├── apps.py + │ │ ├── admin.py + │ │ ├── models.py + │ │ ├── serializers.py + │ │ ├── views.py + │ │ ├── urls.py + │ │ ├── migrations/ + │ │ └── management/ + │ │ + │ ├── linker/ # Internal linking + │ │ ├── __init__.py + │ │ ├── apps.py + │ │ ├── admin.py + │ │ ├── models.py + │ │ ├── serializers.py + │ │ ├── views.py + │ │ ├── urls.py + │ │ └── migrations/ + │ │ + │ ├── optimizer/ # Content optimization + │ │ ├── __init__.py + │ │ ├── apps.py + │ │ ├── admin.py + │ │ ├── models.py + │ │ ├── serializers.py + │ │ ├── views.py + │ │ ├── urls.py + │ │ └── migrations/ + │ │ + │ ├── publisher/ # WordPress publishing + │ │ ├── __init__.py + │ │ ├── apps.py + │ │ ├── views.py + │ │ └── urls.py + │ │ + │ ├── site_builder/ # Site blueprints + │ │ ├── __init__.py + │ │ ├── apps.py + │ │ ├── admin.py + │ │ ├── models.py + │ │ ├── serializers.py + │ │ ├── views.py + │ │ ├── urls.py + │ │ └── migrations/ + │ │ + │ ├── automation/ # Task automation + │ │ ├── __init__.py + │ │ ├── apps.py + │ │ ├── admin.py + │ │ ├── models.py + │ │ ├── serializers.py + │ │ ├── views.py + │ │ ├── urls.py + │ │ └── migrations/ + │ │ + │ ├── integration/ # WordPress integration + │ │ ├── __init__.py + │ │ ├── apps.py + │ │ ├── views.py + │ │ └── urls.py + │ │ + │ ├── billing/ # Credit system + │ │ ├── __init__.py + │ │ ├── apps.py + │ │ ├── admin.py + │ │ ├── models.py + │ │ ├── serializers.py + │ │ ├── views.py + │ │ ├── urls.py + │ │ └── migrations/ + │ │ + │ └── system/ # System settings + │ ├── __init__.py + │ ├── apps.py + │ ├── admin.py + │ ├── models.py # Settings, AI models + │ ├── serializers.py + │ ├── settings_models.py + │ ├── settings_serializers.py + │ ├── settings_views.py + │ ├── settings_admin.py + │ ├── views.py + │ ├── integration_views.py + │ ├── urls.py + │ ├── validators.py + │ ├── utils.py + │ ├── schemas.py + │ ├── management/ + │ └── migrations/ + │ + ├── middleware/ # Custom middleware + │ ├── __init__.py + │ ├── request_id.py # Request ID tracking + │ └── resource_tracker.py # Resource monitoring + │ + ├── tasks/ # Celery tasks + │ └── wordpress_publishing.py + │ + ├── utils/ # Shared utilities + │ ├── __init__.py + │ ├── ai_processor.py + │ ├── content_normalizer.py + │ ├── queue_manager.py + │ └── wordpress.py + │ + ├── urls/ # URL modules + │ └── [module-specific URL configs] + │ + └── migrations/ # ⭐ Database migrations (critical) + └── [all migration files] +``` + +**EXCLUDE from package (installed via package managers):** +- `.venv/` - Virtual environment (created on deployment) +- `__pycache__/` - Python cache files +- `*.pyc`, `*.pyo` - Compiled Python +- `staticfiles/` - Collected static files (generated) +- `logs/` - Log files +- `db.sqlite3`, `*.sql` - Database files +- `celerybeat-schedule` - Celery scheduler state +- Test/debug scripts: `check_*.py`, `fix_*.py`, `verify_*.py`, `diagnose_*.py`, `inject_*.py`, `test_*.py` +- `backup_*.sql` - Database backups + +### Frontend Essential Package Tree + +**Package Only These Files** - Excludes React boilerplate and node_modules: + +``` +frontend/ +├── package.json # ⭐ Dependencies manifest (critical) +├── package-lock.json # Locked dependencies +├── tsconfig.json # TypeScript config (IGNY8-modified) +├── tsconfig.app.json # App-specific TS config +├── tsconfig.node.json # Node-specific TS config +├── vite.config.ts # ⭐ Vite build config (IGNY8-customized) +├── vitest.config.ts # Test configuration +├── postcss.config.js # PostCSS config +├── eslint.config.js # ESLint configuration +├── index.html # Main HTML entry point +├── marketing.html # Marketing site entry (if used) +├── Dockerfile # ⭐ Container config (critical) +├── Dockerfile.dev # Dev container config +├── Caddyfile # Reverse proxy config +│ +├── public/ # Static assets +│ ├── images/ # IGNY8 images +│ └── marketing/ # Marketing assets +│ +└── src/ # ⭐ Application source (all critical) + ├── main.tsx # ⭐ App entry point (IGNY8-specific) + ├── App.tsx # ⭐ Main app component (IGNY8 routing) + ├── index.css # Global styles + ├── vite-env.d.ts # Vite type definitions + ├── svg.d.ts # SVG type definitions + │ + ├── config/ # ⭐ App configuration + │ ├── api.config.ts # API endpoints + │ ├── routes.config.ts # Route definitions + │ └── constants.ts # App constants + │ + ├── types/ # ⭐ TypeScript types (IGNY8 models) + │ ├── index.ts + │ ├── auth.types.ts + │ ├── planner.types.ts + │ ├── writer.types.ts + │ ├── linker.types.ts + │ ├── optimizer.types.ts + │ ├── site.types.ts + │ ├── billing.types.ts + │ └── ... + │ + ├── api/ # ⭐ API client layer + │ ├── automation.api.ts + │ ├── linker.api.ts + │ └── optimizer.api.ts + │ + ├── services/ # ⭐ Service layer + │ ├── api.ts # Base API service + │ ├── integration.api.ts + │ └── siteBuilder.api.ts + │ + ├── store/ # ⭐ Zustand state management + │ ├── authStore.ts + │ ├── billingStore.ts + │ ├── plannerStore.ts + │ ├── siteStore.ts + │ ├── siteDefinitionStore.ts + │ ├── settingsStore.ts + │ ├── sectorStore.ts + │ ├── onboardingStore.ts + │ ├── columnVisibilityStore.ts + │ └── pageSizeStore.ts + │ + ├── context/ # React Context providers + │ ├── ThemeContext.tsx + │ └── HeaderMetricsContext.tsx + │ + ├── hooks/ # Custom React hooks + │ ├── useAuth.ts + │ ├── useDebounce.ts + │ ├── useLocalStorage.ts + │ └── ... + │ + ├── layout/ # ⭐ App layout components + │ ├── AppLayout.tsx # Main layout + │ ├── AppHeader.tsx # Header + │ ├── AppSidebar.tsx # Sidebar navigation + │ ├── SidebarWidget.tsx + │ └── Backdrop.tsx + │ + ├── components/ # ⭐ IGNY8-specific components + │ ├── auth/ # Authentication + │ │ ├── ProtectedRoute.tsx + │ │ └── ... + │ │ + │ ├── common/ # Shared components + │ │ ├── ErrorBoundary.tsx + │ │ ├── LoadingStateMonitor.tsx + │ │ ├── GlobalErrorDisplay.tsx + │ │ ├── ScrollToTop.tsx + │ │ ├── ModuleGuard.tsx + │ │ └── ... + │ │ + │ ├── header/ # Header components + │ ├── sidebar/ # Sidebar components + │ ├── navigation/ # Navigation + │ ├── dashboard/ # Dashboard widgets + │ ├── content/ # Content components + │ ├── integration/ # Integration UI + │ ├── linker/ # Linker components + │ ├── optimizer/ # Optimizer components + │ ├── publishing/ # Publishing UI + │ ├── sites/ # Site management + │ ├── tasks/ # Task management + │ ├── onboarding/ # Onboarding flow + │ ├── debug/ # Debug tools + │ │ + │ ├── ui/ # UI primitives + │ │ ├── toast/ + │ │ ├── button/ + │ │ ├── modal/ + │ │ └── ... + │ │ + │ ├── tables/ # Table components + │ ├── form/ # Form components + │ ├── charts/ # Chart components + │ └── shared/ # Shared UI + │ + ├── pages/ # ⭐ Page components (routes) + │ ├── Dashboard/ + │ │ └── Home.tsx # Main dashboard + │ │ + │ ├── AuthPages/ # Auth pages + │ │ ├── SignIn.tsx + │ │ └── SignUp.tsx + │ │ + │ ├── Planner/ # Planner module + │ │ ├── Dashboard.tsx + │ │ ├── Keywords.tsx + │ │ ├── Clusters.tsx + │ │ ├── ClusterDetail.tsx + │ │ ├── Ideas.tsx + │ │ └── KeywordOpportunities.tsx + │ │ + │ ├── Writer/ # Writer module + │ │ ├── Dashboard.tsx + │ │ ├── Tasks.tsx + │ │ ├── ContentLibrary.tsx + │ │ └── ... + │ │ + │ ├── Linker/ # Linker module + │ ├── Optimizer/ # Optimizer module + │ ├── Sites/ # Site management + │ ├── Settings/ # Settings + │ ├── Billing/ # Billing + │ ├── Automation/ # Automation + │ ├── Help/ # Help pages + │ ├── Setup/ # Setup wizard + │ ├── Reference/ # Reference pages + │ ├── Thinker/ # Thinker module + │ └── OtherPage/ + │ └── NotFound.tsx + │ + ├── modules/ # Module-specific logic + │ └── siteBuilder/ + │ + ├── templates/ # Page templates + ├── icons/ # Custom icons + ├── styles/ # ⭐ IGNY8 styles + │ └── igny8-colors.css # Custom color scheme + │ + ├── utils/ # Utility functions + │ ├── dateUtils.ts + │ ├── formatters.ts + │ └── ... + │ + ├── marketing/ # Marketing site (optional) + │ └── [marketing components] + │ + └── __tests__/ # Tests + └── [test files] +``` + +**EXCLUDE from package (installed via npm):** +- `node_modules/` - Dependencies (installed via `npm install`) +- `dist/` - Build output (generated) +- `banner.png` - May be optional +- `DESIGN_SYSTEM.md`, `MIGRATION_GUIDE.md`, `README.md`, `LICENSE.md` - Documentation (optional) + +### Installation & Portability Guide + +#### Backend Deployment Steps + +```bash +# 1. Copy backend essential files to new infrastructure +# 2. Set up Python environment +python -m venv .venv +source .venv/bin/activate # or .venv\Scripts\activate on Windows + +# 3. Install dependencies from requirements.txt +pip install -r requirements.txt + +# 4. Configure environment variables (create .env file) +SECRET_KEY= +DEBUG=False +DATABASE_URL=postgresql://user:pass@host:5432/dbname +REDIS_URL=redis://redis:6379/0 +ALLOWED_HOSTS=yourdomain.com + +# 5. Run migrations to set up database +python manage.py migrate + +# 6. Create superuser +python manage.py createsuperuser + +# 7. Collect static files +python manage.py collectstatic --noinput + +# 8. Start services +# Application server +gunicorn igny8_core.wsgi:application --bind 0.0.0.0:8000 + +# Celery worker (separate terminal) +celery -A igny8_core worker --loglevel=info + +# Celery beat scheduler (separate terminal) +celery -A igny8_core beat --loglevel=info +``` + +#### Frontend Deployment Steps + +```bash +# 1. Copy frontend essential files to new infrastructure +# 2. Install dependencies from package.json +npm install +# or +npm ci # for production (uses package-lock.json) + +# 3. Configure environment (create .env file) +VITE_API_BASE_URL=https://api.yourdomain.com +VITE_APP_NAME=IGNY8 + +# 4. Build for production +npm run build + +# 5. Serve static files (multiple options) +# Option A: Using Caddy (recommended) +caddy run --config Caddyfile + +# Option B: Using preview mode +npm run preview + +# Option C: Using static server +npx serve -s dist -l 5173 +``` + +#### Docker Deployment (Recommended) + +```bash +# Build and run with Docker Compose +docker-compose -f docker-compose.app.yml up -d + +# Services will be available at: +# - Frontend: http://localhost:5173 +# - Backend API: http://localhost:8000 +# - Admin: http://localhost:8000/igny8-admin/ +``` + +### Key Differences: Framework Files vs IGNY8 Files + +#### Backend + +**Framework Files (NOT in package):** +- Django's own code (installed via pip) +- Standard Django project structure created by `django-admin startproject` +- Generic migration files for Django's contrib apps +- Python standard library modules + +**IGNY8-Specific Files (IN package):** +- All files in `igny8_core/` with custom business logic +- Custom models, views, serializers, URLs +- AI framework implementation +- Business logic services +- Module-specific code (planner, writer, linker, etc.) +- Custom middleware and utilities +- Database migrations for IGNY8 models +- `settings.py` with IGNY8 configuration +- `requirements.txt` (dependency manifest) + +#### Frontend + +**Framework Files (NOT in package):** +- React library itself (installed via npm) +- node_modules dependencies +- TypeScript compiler +- Vite build tool +- TailwindCSS framework + +**IGNY8-Specific Files (IN package):** +- All `.tsx` and `.ts` files in `src/` +- Custom components, pages, layouts +- State management stores +- API client implementation +- Type definitions for IGNY8 models +- Custom hooks and utilities +- Routing configuration +- Custom styles (`igny8-colors.css`) +- `package.json` (dependency manifest) +- `vite.config.ts` with IGNY8-specific build config + +### Portability Checklist + +✅ **Before packaging:** +- [ ] Remove all `.env` files (environment-specific) +- [ ] Remove database files (`.sqlite3`, `*.sql` backups) +- [ ] Remove logs and temporary files +- [ ] Remove virtual environments (`.venv/`, `node_modules/`) +- [ ] Remove build artifacts (`dist/`, `staticfiles/`, `__pycache__/`) +- [ ] Keep all migration files (critical for database schema) +- [ ] Keep `requirements.txt` and `package.json` (dependency manifests) +- [ ] Keep Dockerfile and docker-compose files + +✅ **After deployment to new infrastructure:** +- [ ] Install dependencies (`pip install -r requirements.txt`, `npm install`) +- [ ] Configure environment variables for new infrastructure +- [ ] Run database migrations +- [ ] Create initial superuser +- [ ] Collect static files (backend) +- [ ] Build frontend assets +- [ ] Configure reverse proxy (Caddy/Nginx) +- [ ] Set up SSL certificates +- [ ] Configure Redis and Celery workers +- [ ] Test all API endpoints +- [ ] Verify WordPress integration works + +### Size Estimation + +**Backend Package:** ~5-10 MB (excluding virtual environment and dependencies) +**Frontend Package:** ~2-5 MB (excluding node_modules) +**Total Application Code:** ~7-15 MB + +**After Installation:** +- Backend with dependencies: ~200-300 MB +- Frontend with dependencies: ~300-500 MB +- Total deployed: ~500-800 MB + +--- + ## Deployment Architecture ### Production Stack