# IGNY8 Development Rules & Standards **Project:** IGNY8 - AI-Powered Content Platform **Version:** v1.0.0 **Last Updated:** December 12, 2025 --- ## 📋 General Development Principles ### 1. **Always Read Documentation First** Before making changes, consult these critical docs: - `ARCHITECTURE-KNOWLEDGE-BASE.md` - System architecture and design patterns - `CHANGELOG.md` - Recent changes and version history - `IGNY8-COMPLETE-FEATURES-GUIDE.md` - Complete feature set and capabilities - `docs/00-SYSTEM/` - Core system architecture - `docs/10-BACKEND/` - Backend models, services, APIs - `docs/20-API/` - API endpoint documentation - `docs/30-FRONTEND/` - Frontend components and architecture - `docs/40-WORKFLOWS/` - Business workflows and processes ### 2. **Maintain Consistency** - **API Design:** Follow existing RESTful patterns in `backend/igny8_core/*/views.py` - **Models:** Use existing base classes (`SoftDeletableModel`, `AccountBaseModel`, `SiteSectorBaseModel`) - **Services:** Follow service pattern in `backend/igny8_core/business/*/services/` - **AI Functions:** Use AI framework in `backend/igny8_core/ai/` (not legacy `utils/ai_processor.py`) - **Frontend Components:** Use existing component library in `frontend/src/components/` - **Styling:** Use TailwindCSS classes, follow existing design system in `frontend/DESIGN_SYSTEM.md` - **State Management:** Use Zustand stores in `frontend/src/store/` ### 3. **Multi-Tenancy Rules** - **ALWAYS scope by account:** Every query must filter by account - **Site/Sector scoping:** Use `SiteSectorBaseModel` for site-specific data - **Permissions:** Check permissions via `IsAuthenticatedAndActive`, `HasTenantAccess`, role-based permissions - **No cross-tenant access:** Validate account ownership before operations ### 4. **API Endpoint Rules** - **Use existing API structure:** All user-facing endpoints under `/api/v1//`, admin endpoints under `/api/v1//admin/` - **No parallel API systems:** Register all endpoints in module's `urls.py`, test via Swagger at `/api/docs/` before documenting - **Document in Swagger:** Ensure drf-spectacular auto-generates docs; verify endpoint appears at `/api/docs/` and `/api/schema/` --- ## 📝 Change Management & Versioning alwys udpated changelog with incremental updates, as fixed aded or modified for each version update, dotn remove or modify teh exsitng version changes ### Versioning Scheme: `v..` **Example:** v1.2.5 - `MAJOR when asked` (1.x.x): Breaking changes, major features, architecture changes - `MAJOR` (x.2.x): New features, modules, significant enhancements - `MINOR/PATCH` (x.x.5): Bug fixes, small improvements, refactors ### Changelog Update Rules #### **For EVERY Change:** 1. **Update version number** in `CHANGELOG.md` 2. **Increment PATCH** (v1.0.x → v1.0.1) for: - Bug fixes - Small improvements - Code refactors - Documentation updates - UI/UX tweaks 3. **Increment MINOR** (v1.x.0 → v1.1.0) for: - New features - New API endpoints - New components - New services - Significant enhancements 4. **Increment MAJOR** (vx.0.0 → v2.0.0) for: - Breaking API changes - Database schema breaking changes - Architecture overhauls - Major refactors affecting multiple modules #### **Changelog Entry Format:** ```markdown ## v1.2.5 - December 12, 2025 ### Fixed - User logout issue when switching accounts - Payment confirmation modal amount display ### Changed - Updated session storage from database to Redis - Enhanced credit balance widget UI ### Added - Plan limits enforcement system - Monthly reset task for usage tracking ``` ### **For Major Refactors:** 1. **Create detailed TODO list** before starting 2. **Document current state** in CHANGELOG 3. **Create implementation checklist** (markdown file in root or docs/) 4. **Track progress** with checklist updates 5. **Test thoroughly** before committing 6. **Update CHANGELOG** with all changes made 7. **Update version** to next MINOR or MAJOR --- ## 🏗️ Code Organization Standards ### Backend Structure ``` backend/igny8_core/ ├── auth/ # Authentication, users, accounts, plans ├── business/ # Business logic services │ ├── automation/ # Automation pipeline │ ├── billing/ # Billing, credits, invoices │ ├── content/ # Content generation │ ├── integration/ # External integrations │ ├── linking/ # Internal linking │ ├── optimization/ # Content optimization │ ├── planning/ # Keywords, clusters, ideas │ └── publishing/ # WordPress publishing ├── ai/ # AI framework (NEW - use this) ├── utils/ # Utility functions ├── tasks/ # Celery tasks └── modules/ # Legacy modules (being phased out) ``` ### Frontend Structure ``` frontend/src/ ├── components/ # Reusable components ├── pages/ # Page components ├── store/ # Zustand state stores ├── services/ # API service layer ├── hooks/ # Custom React hooks ├── utils/ # Utility functions ├── types/ # TypeScript types └── marketing/ # Marketing site ``` --- ## 🔧 Development Workflow ### 1. **Planning Phase** - [ ] Read relevant documentation - [ ] Understand existing patterns - [ ] Create TODO list for complex changes - [ ] Identify affected components/modules - [ ] Plan database changes (if any) ### 2. **Implementation Phase** - [ ] Follow existing code patterns - [ ] Use proper base classes and mixins - [ ] Add proper error handling - [ ] Validate input data - [ ] Check permissions and scope - [ ] Write clean, documented code - [ ] Use type hints (Python) and TypeScript types ### 3. **Testing Phase** - [ ] Test locally with development data - [ ] Test multi-tenancy isolation - [ ] Test permissions and access control - [ ] Test error cases - [ ] Verify no breaking changes - [ ] Check frontend-backend integration ### 4. **Documentation Phase** - [ ] Update CHANGELOG.md - [ ] Update version number - [ ] Update relevant docs (if architecture/API changes) - [ ] Add code comments for complex logic - [ ] Update API documentation (if endpoints changed) --- ## 🎯 Specific Development Rules ### Backend Development #### **Models:** ```python # ALWAYS inherit from proper base classes from igny8_core.auth.models import SiteSectorBaseModel class MyModel(SoftDeletableModel, SiteSectorBaseModel): # Your fields here pass ``` #### **Services:** ```python # Follow service pattern class MyService: def __init__(self): self.credit_service = CreditService() self.limit_service = LimitService() def my_operation(self, account, site, **kwargs): # 1. Validate permissions # 2. Check limits/credits # 3. Perform operation # 4. Track usage # 5. Return result pass ``` #### **API Views:** ```python # Use proper permission classes class MyViewSet(viewsets.ModelViewSet): permission_classes = [IsAuthenticatedAndActive, HasTenantAccess] def get_queryset(self): # ALWAYS scope by account return MyModel.objects.filter( site__account=self.request.user.account ) ``` #### **Migrations:** - Run `python manage.py makemigrations` after model changes - Test migrations: `python manage.py migrate --plan` - Never edit existing migrations - Use data migrations for complex data changes ### Frontend Development #### **Components:** ```typescript // Use existing component library import { Card } from '@/components/ui/card'; import Button from '@/components/ui/button/Button'; // Follow naming conventions export default function MyComponent() { // Component logic } ``` #### **State Management:** ```typescript // Use Zustand stores import { useAuthStore } from '@/store/authStore'; const { user, account } = useAuthStore(); ``` #### **API Calls:** ```typescript // Use fetchAPI from services/api.ts import { fetchAPI } from '@/services/api'; const data = await fetchAPI('/v1/my-endpoint/'); ``` #### **Styling:** ```typescript // Use TailwindCSS classes

My Heading

``` --- ## 🚫 Common Pitfalls to Avoid ### **DON'T:** - ❌ Skip account scoping in queries - ❌ Use legacy AI processor (`utils/ai_processor.py`) - use `ai/` framework - ❌ Hardcode values - use settings or constants - ❌ Forget error handling - ❌ Skip permission checks - ❌ Create duplicate components - reuse existing - ❌ Use inline styles - use TailwindCSS - ❌ Forget to update CHANGELOG - ❌ Use workarounds - fix the root cause - ❌ Skip migrations after model changes ### **DO:** - ✅ Read documentation before coding - ✅ Follow existing patterns - ✅ Use proper base classes - ✅ Check permissions and limits - ✅ Handle errors gracefully - ✅ Return valid errors, not fallbacks - ✅ Update CHANGELOG for every change - ✅ Test multi-tenancy isolation - ✅ Use TypeScript types - ✅ Write clean, documented code --- ## 🔍 Code Review Checklist Before committing code, verify: - [ ] Follows existing code patterns - [ ] Properly scoped by account/site - [ ] Permissions checked - [ ] Error handling implemented - [ ] No breaking changes - [ ] CHANGELOG.md updated - [ ] Version number incremented - [ ] Documentation updated (if needed) - [ ] Tested locally - [ ] No console errors or warnings - [ ] TypeScript types added/updated - [ ] Migrations created (if model changes) --- ## 📚 Key Architecture Concepts ### **Credit System:** - All AI operations cost credits - Check credits before operation: `CreditService.check_credits()` - Deduct after operation: `CreditService.deduct_credits()` - Track in `CreditUsageLog` table ### **Limit System:** - Hard limits: Persistent (sites, users, keywords, clusters) - Monthly limits: Reset on billing cycle (ideas, words, images) - Track in `PlanLimitUsage` table - Check before operation: `LimitService.check_limit()` ### **AI Framework:** - Use `ai/engine.py` for AI operations - Use `ai/functions/` for specific AI tasks - Use `ai/models.py` for tracking - Don't use legacy `utils/ai_processor.py` ### **Multi-Tenancy:** - Every request has `request.user.account` - All models scope by account directly or via site - Use `AccountBaseModel` or `SiteSectorBaseModel` - Validate ownership before mutations --- ## 🎨 Design System ### **Colors:** - Primary: Blue (#0693e3) - Success: Green (#0bbf87) - Error: Red (#ef4444) - Warning: Yellow (#f59e0b) - Info: Blue (#3b82f6) ### **Typography:** - Headings: font-bold - Body: font-normal - Small text: text-sm - Large text: text-lg, text-xl, text-2xl ### **Spacing:** - Padding: p-4, p-6 (standard) - Margin: mt-4, mb-6 (standard) - Gap: gap-4, gap-6 (standard) ### **Components:** - Card: `` with padding and shadow - Button: `