salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

rules and planning finalize for docs to be standrd always

Browse Source
This commit is contained in:
IGNY8 VPS (Salman)
2025-12-27 00:55:50 +00:00
parent 7a9fa8fd8f
commit 7af4190e6d
5 changed files with 228 additions and 247 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
.rules
View File

@@ -1,6 +1,6 @@
# IGNY8 AI Agent Rules # IGNY8 AI Agent Rules
**Version:** 1.1.0 | **Updated:** December 27, 2025 **Version:** 1.1.3 | **Updated:** December 27, 2025
--- ---
@@ -26,6 +26,25 @@
--- ---
## ⚠️ Module Status
| Module | Status | Notes |
|--------|--------|-------|
| Planner | ✅ Active | Keywords, Clusters, Ideas |
| Writer | ✅ Active | Tasks, Content, Images |
| Automation | ✅ Active | 7-stage pipeline |
| Billing | ✅ Active | Credits, Plans |
| Publisher | ✅ Active | WordPress publishing |
| **Linker** | ⏸️ Inactive | Exists but disabled - Phase 2 |
| **Optimizer** | ⏸️ Inactive | Exists but disabled - Phase 2 |
| **SiteBuilder** | ❌ Removed | Code exists but NOT part of app - mark for removal in TODOS.md |
**Important:**
- Do NOT work on Linker/Optimizer unless specifically requested
- SiteBuilder code is deprecated - if found, add to `TODOS.md` for cleanup
---
## 🐳 Docker Commands (IMPORTANT!) ## 🐳 Docker Commands (IMPORTANT!)
**Container Names:** **Container Names:**
@@ -57,26 +76,44 @@ docker logs igny8_celery_worker -f
--- ---
## 📊 Data Scoping (CRITICAL!)
**Understand which data is scoped where:**
| Scope | Models | Notes |
|-------|--------|-------|
| **Global (Platform-wide)** | `GlobalIntegrationSettings`, `GlobalAIPrompt`, `GlobalAuthorProfile`, `GlobalStrategy`, `GlobalModuleSettings`, `Industry`, `SeedKeyword` | Admin-only, shared by ALL accounts |
| **Account-scoped** | `Account`, `User`, `Plan`, `IntegrationSettings`, `ModuleEnableSettings`, `AISettings`, `AIPrompt`, `AuthorProfile` | Filter by `account` |
| **Site+Sector-scoped** | `Keywords`, `Clusters`, `ContentIdeas`, `Tasks`, `Content`, `Images` | Filter by `site` AND optionally `sector` |
**Key Rules:**
- Global settings: NO account filtering (platform-wide, admin managed)
- Account models: Use `AccountBaseModel`, filter by `request.user.account`
- Site/Sector models: Use `SiteSectorBaseModel`, filter by `site` and `sector`
---
## ✅ Rules (One Line Each) ## ✅ Rules (One Line Each)
### Before Coding ### Before Coding
1. **Read docs first** - Always read the relevant module doc from `docs/10-MODULES/` before changing code 1. **Read docs first** - Always read the relevant module doc from `docs/10-MODULES/` before changing code
2. **Check existing patterns** - Search codebase for similar implementations before creating new ones 2. **Check existing patterns** - Search codebase for similar implementations before creating new ones
3. **Use existing components** - Never duplicate; reuse components from `frontend/src/components/` 3. **Use existing components** - Never duplicate; reuse components from `frontend/src/components/`
4. **Check data scope** - Know if your model is Global, Account, or Site/Sector scoped (see table above)
### During Coding ### During Coding
4. **Scope by account** - Every query must filter by `account` (use `AccountBaseModel` or `SiteSectorBaseModel`) 5. **Use correct base class** - Global: `models.Model`, Account: `AccountBaseModel`, Site: `SiteSectorBaseModel`
5. **Use AI framework** - Use `backend/igny8_core/ai/` for AI operations, NOT legacy `utils/ai_processor.py` 6. **Use AI framework** - Use `backend/igny8_core/ai/` for AI operations, NOT legacy `utils/ai_processor.py`
6. **Follow service pattern** - Business logic in `backend/igny8_core/business/*/services/` 7. **Follow service pattern** - Business logic in `backend/igny8_core/business/*/services/`
7. **Check permissions** - Use `IsAuthenticatedAndActive`, `HasTenantAccess` in views 8. **Check permissions** - Use `IsAuthenticatedAndActive`, `HasTenantAccess` in views
8. **Use TypeScript types** - All frontend code must be typed 9. **Use TypeScript types** - All frontend code must be typed
9. **Use TailwindCSS** - No inline styles; follow `frontend/DESIGN_SYSTEM.md` 10. **Use TailwindCSS** - No inline styles; follow `frontend/DESIGN_SYSTEM.md`
### After Coding ### After Coding
10. **Update CHANGELOG.md** - Every commit needs a changelog entry with git reference 11. **Update CHANGELOG.md** - Every commit needs a changelog entry with git reference
11. **Increment version** - PATCH for fixes, MINOR for features, MAJOR for breaking changes 12. **Increment version** - PATCH for fixes, MINOR for features, MAJOR for breaking changes
12. **Update docs** - If you changed APIs or architecture, update relevant docs in `docs/` 13. **Update docs** - If you changed APIs or architecture, update relevant docs in `docs/`
13. **Run migrations** - After model changes: `docker exec -it igny8_backend python manage.py makemigrations` 14. **Run migrations** - After model changes: `docker exec -it igny8_backend python manage.py makemigrations`
--- ---
@@ -117,10 +154,13 @@ docker logs igny8_celery_worker -f
- ❌ Create duplicate components - ❌ Create duplicate components
- ❌ Use `docker-compose` for exec commands (use `docker exec`) - ❌ Use `docker-compose` for exec commands (use `docker exec`)
- ❌ Use legacy `utils/ai_processor.py` - ❌ Use legacy `utils/ai_processor.py`
- ❌ Skip account scoping in queries - ❌ Add account filtering to Global models (they're platform-wide!)
- ❌ Forget site/sector filtering on content models
- ❌ Forget to update CHANGELOG - ❌ Forget to update CHANGELOG
- ❌ Use inline styles (use TailwindCSS) - ❌ Use inline styles (use TailwindCSS)
- ❌ Hardcode values (use settings/constants) - ❌ Hardcode values (use settings/constants)
- ❌ Work on Linker/Optimizer (inactive modules - Phase 2)
- ❌ Use any SiteBuilder code (deprecated - mark for removal)
--- ---
@@ -134,9 +174,42 @@ docker logs igny8_celery_worker -f
| Billing | `/api/v1/billing/` | | Billing | `/api/v1/billing/` |
| Integration | `/api/v1/integration/` | | Integration | `/api/v1/integration/` |
| System | `/api/v1/system/` | | System | `/api/v1/system/` |
| Publisher | `/api/v1/publisher/` |
**API Docs:** http://localhost:8000/api/docs/ **API Docs:** https://api.igny8.com/api/docs/
**Admin:** https://api.igny8.com/admin/
**App:** https://app.igny8.com/
---
## 📄 Documentation Rules
**Root folder MD files allowed:**
- `CHANGELOG.md` - Version history
- `README.md` - Project quickstart
- `IGNY8-APP.md` - Executive summary
- `TODOS.md` - Cleanup tracking
**All other docs go in `/docs/` folder:**
```
docs/
├── INDEX.md # Master navigation
├── 00-SYSTEM/ # Architecture, auth, tenancy
├── 10-MODULES/ # One file per module
├── 20-API/ # API endpoints
├── 30-FRONTEND/ # Pages, stores
├── 40-WORKFLOWS/ # Cross-module flows
└── 90-REFERENCE/ # Models, AI functions
```
**When updating docs:**
| Change Type | Update These Files |
|-------------|-------------------|
| New endpoint | Module doc + `docs/20-API/ENDPOINTS.md` |
| New model | Module doc + `docs/90-REFERENCE/MODELS.md` |
| New page | Module doc + `docs/30-FRONTEND/PAGES.md` |
| New module | Create module doc + update `docs/INDEX.md` |
**DO NOT** create random MD files - update existing docs instead.
--- ---
@@ -144,7 +217,7 @@ docker logs igny8_celery_worker -f
- [ ] Read relevant module docs - [ ] Read relevant module docs
- [ ] Used existing components/patterns - [ ] Used existing components/patterns
- [ ] Account scoped all queries - [ ] Correct data scope (Global/Account/Site)
- [ ] Updated CHANGELOG.md with git reference - [ ] Updated CHANGELOG.md with git reference
- [ ] Updated version number - [ ] Updated version number
- [ ] Ran migrations if model changed - [ ] Ran migrations if model changed

38
CHANGELOG.md
View File

@@ -1,6 +1,6 @@
# IGNY8 Change Log # IGNY8 Change Log
**Current Version:** 1.1.1 **Current Version:** 1.1.3
**Last Updated:** December 27, 2025 **Last Updated:** December 27, 2025
--- ---
@@ -9,6 +9,8 @@
| Version | Date | Summary | | Version | Date | Summary |
|---------|------|---------| |---------|------|---------|
| 1.1.3 | Dec 27, 2025 | Merged RULES.md into .rules |
| 1.1.2 | Dec 27, 2025 | Module status documentation, TODOS.md |
| 1.1.1 | Dec 27, 2025 | Simplified AI agent rules file | | 1.1.1 | Dec 27, 2025 | Simplified AI agent rules file |
| 1.1.0 | Dec 25, 2025 | UX overhaul, page consolidation, pre-launch audit | | 1.1.0 | Dec 25, 2025 | UX overhaul, page consolidation, pre-launch audit |
| 1.0.5 | Dec 12, 2025 | Purchase Credits tab, UI reorganization | | 1.0.5 | Dec 12, 2025 | Purchase Credits tab, UI reorganization |
@@ -20,16 +22,48 @@
--- ---
## v1.1.3 - December 27, 2025
### Changed
- **Merged RULES.md into .rules** - Single rules file for AI agents
- Added documentation rules section to `.rules`
- Deleted redundant `RULES.md` file
- Now only one rules file: `.rules`
---
## v1.1.2 - December 27, 2025
### Added
- **Module Status section** in `.rules` file showing active/inactive modules
- Linker, Optimizer marked as ⏸️ Inactive (Phase 2)
- SiteBuilder marked as ❌ Removed (deprecated)
- **TODOS.md** file for tracking deprecated code cleanup
- Template for logging SiteBuilder and other deprecated code
### Changed
- Updated "Don't Do" list with warnings about inactive modules and SiteBuilder
---
## v1.1.1 - December 27, 2025 ## v1.1.1 - December 27, 2025
### Changed ### Changed
- **Rules File Overhaul**: Simplified `.rules` file for AI agents - **Rules File Overhaul**: Simplified `.rules` file for AI agents
- Reduced from 300+ lines to ~120 lines - Reduced from 300+ lines to ~150 lines
- Added clear Docker container names and correct exec commands - Added clear Docker container names and correct exec commands
- Added one-line rules format for quick reading - Added one-line rules format for quick reading
- Added quick reference table pointing to INDEX.md - Added quick reference table pointing to INDEX.md
- Removed verbose code examples (agents should read actual codebase) - Removed verbose code examples (agents should read actual codebase)
- Added changelog format with git reference requirement - Added changelog format with git reference requirement
- **Added Data Scoping section** clarifying Global vs Account vs Site/Sector models
- Global settings (API keys, prompts, author profiles) are platform-wide, NOT account-scoped
- Site/Sector models (Keywords, Clusters, Content) need site+sector filtering
### Added
- **MODELS.md**: Added Data Scoping Overview table and Global Models section
- Documents `GlobalIntegrationSettings`, `GlobalAIPrompt`, `GlobalAuthorProfile`
- Clear distinction between Global/Account/Site scoped models
--- ---

229
RULES.md
View File

@@ -1,229 +0,0 @@
# IGNY8 Documentation Rules
**Version:** 1.0
**Last Updated:** December 25, 2025
**Purpose:** Rules for maintaining consistent, accurate documentation
---
## Core Principles
1. **Single Source of Truth** - One file per topic, no duplicates
2. **Code is King** - Documentation reflects actual code, not plans
3. **Tables Over Prose** - Use tables for lists of 3+ items
4. **Code Paths Always** - Every feature links to exact files
5. **Brief But Complete** - No fluff, every word has purpose
---
## File Structure Rules
### Root Folder (/)
Only these MD files allowed in root:
- `CHANGELOG.md` - Version history
- `RULES.md` - This file
- `IGNY8-APP.md` - Executive summary (non-technical)
- `README.md` - Project quickstart
**DO NOT CREATE** random MD files in root. All documentation goes in `/docs/`.
### Docs Folder (/docs/)
```
docs/
├── INDEX.md # Master navigation (update when adding docs)
├── 00-SYSTEM/ # Architecture, auth, tenancy
├── 10-MODULES/ # One file per module
├── 20-API/ # API endpoints and schemas
├── 30-FRONTEND/ # Pages, stores, components
├── 40-WORKFLOWS/ # Cross-module flows
└── 90-REFERENCE/ # Models, AI functions, troubleshooting
```
---
## Document Templates
### Module Document
Every module doc must include:
```markdown
# [Module Name]
**Last Verified:** YYYY-MM-DD
**Status:** ✅ Active | ⏸️ Inactive
**Backend Path:** `backend/...`
**Frontend Path:** `frontend/...`
## Quick Reference
| What | File | Key Items |
|------|------|-----------|
## Data Models
[Tables with fields]
## API Endpoints
| Method | Path | Handler | Purpose |
## Business Logic
[Key operations with credit costs]
## Frontend Pages
[Routes and components]
## Common Issues
| Issue | Cause | Fix |
## Planned Changes
| Feature | Status | Description |
```
### Status Values
For Planned Changes tables:
- ✅ Completed
- 🐛 Bug (known issue)
- 🔜 Planned (confirmed future work)
- ⏸️ Pending (waiting on dependency)
- ❌ Cancelled
---
## Update Rules
### When to Update Documentation
| Event | Action |
|-------|--------|
| New feature added | Update relevant module doc |
| Bug fixed | Add to Common Issues if recurring |
| API endpoint changed | Update API endpoints table |
| Model changed | Update data models section |
| Config changed | Update relevant doc |
| Release | Update CHANGELOG.md |
### What to Update
| Change Type | Files to Update |
|-------------|-----------------|
| New module | Create module doc, update INDEX.md |
| New endpoint | Module doc + API/ENDPOINTS.md |
| New model | Module doc + 90-REFERENCE/MODELS.md |
| Frontend page | Module doc + 30-FRONTEND/PAGES.md |
| Bug fix | Common Issues in relevant doc |
### "Last Verified" Dates
Update `Last Verified:` date when:
- You confirm the doc matches current code
- After making changes to the doc
- During documentation reviews
---
## Writing Style
### Do
- Use present tense ("Creates" not "Will create")
- Use tables for any list of 3+ items
- Include exact file paths
- Link to related docs
- Keep sentences short
### Don't
- Don't explain obvious things
- Don't use jargon without defining
- Don't duplicate info across files
- Don't use passive voice
- Don't leave TODOs in docs (use Planned Changes table)
### Code Path Format
```
Backend: `backend/igny8_core/modules/planner/views.py:KeywordViewSet.bulk_delete`
Frontend: `frontend/src/pages/Planner/Keywords.tsx:handleBulkDelete`
```
---
## AI Agent Instructions
When AI agents (Copilot, Claude, etc.) make changes:
### After Code Changes
1. Identify which module(s) were modified
2. Update the relevant module doc(s)
3. If API changed, update API endpoints
4. If model changed, update MODELS.md
5. Update CHANGELOG.md for significant changes
### What NOT to Do
- DO NOT create new MD files in root folder
- DO NOT create "summary" or "implementation" docs
- DO NOT duplicate existing documentation
- DO NOT add verbose explanations
- DO NOT leave placeholder content
### Verification Checklist
After documentation update:
- [ ] File is in correct location (/docs/ structure)
- [ ] INDEX.md updated if new file added
- [ ] No duplicate information
- [ ] All code paths are accurate
- [ ] Tables used appropriately
- [ ] Last Verified date updated
---
## Documentation Review Schedule
| Frequency | Action |
|-----------|--------|
| Per commit | Update affected docs |
| Weekly | Review recent changes vs docs |
| Monthly | Full audit: code vs docs |
| Per release | Update CHANGELOG.md, verify all docs |
---
## Quick Reference: File Locations
| Topic | File |
|-------|------|
| Master navigation | `docs/INDEX.md` |
| Architecture | `docs/00-SYSTEM/ARCHITECTURE.md` |
| Authentication | `docs/00-SYSTEM/AUTH-FLOWS.md` |
| Multi-tenancy | `docs/00-SYSTEM/TENANCY.md` |
| Planner module | `docs/10-MODULES/PLANNER.md` |
| Writer module | `docs/10-MODULES/WRITER.md` |
| Billing module | `docs/10-MODULES/BILLING.md` |
| Automation | `docs/10-MODULES/AUTOMATION.md` |
| Integrations | `docs/10-MODULES/INTEGRATIONS.md` |
| Settings | `docs/10-MODULES/SYSTEM-SETTINGS.md` |
| Linker (inactive) | `docs/10-MODULES/LINKER.md` |
| Optimizer (inactive) | `docs/10-MODULES/OPTIMIZER.md` |
| Publisher | `docs/10-MODULES/PUBLISHER.md` |
| API endpoints | `docs/20-API/ENDPOINTS.md` |
| All models | `docs/90-REFERENCE/MODELS.md` |
| Troubleshooting | `docs/90-REFERENCE/TROUBLESHOOTING.md` |
| Version history | `CHANGELOG.md` |
| Executive summary | `IGNY8-APP.md` |
---
## Enforcement
These rules are enforced by:
1. Code review checklist includes documentation
2. AI agents instructed to follow these rules
3. Monthly documentation audits
4. CHANGELOG must be updated for releases
**When in doubt: Update the existing doc, don't create a new file.**

46
TODOS.md Normal file
View File

@@ -0,0 +1,46 @@
# IGNY8 Cleanup TODOs
**Last Updated:** December 27, 2025
---
## 🗑️ Code Marked for Removal
### SiteBuilder (Deprecated)
SiteBuilder module is completely removed from the app. Any code found related to it should be cleaned up.
| File/Location | Type | Status | Notes |
|---------------|------|--------|-------|
| *Add entries here when found* | | | |
**How to identify SiteBuilder code:**
- References to `sitebuilder`, `site_builder`, `SiteBuilder`
- Components/pages with "SiteBuilder" in name
- API endpoints containing `sitebuilder`
- Models or services for building sites using IGNY8
---
## ⏸️ Inactive Modules (Phase 2)
These modules exist but are NOT active. Do not modify unless specifically requested.
| Module | Status | Planned Activation |
|--------|--------|-------------------|
| Linker | ⏸️ Disabled | Phase 2 |
| Optimizer | ⏸️ Disabled | Phase 2 |
---
## 📝 Found Items Log
*When you find deprecated code during development, add it here:*
```markdown
### [Date] - [Found By]
- **File:** path/to/file
- **Type:** SiteBuilder / Other
- **Action Needed:** Remove / Refactor
- **Notes:** Description
```

59
docs/90-REFERENCE/MODELS.md
View File

@@ -1,6 +1,63 @@
# Database Models Reference # Database Models Reference
**Last Verified:** December 25, 2025 **Last Verified:** December 27, 2025
---
## Data Scoping Overview
| Scope | Models | Base Class | Filter By |
|-------|--------|------------|-----------|
| **Global** | `GlobalIntegrationSettings`, `GlobalAIPrompt`, `GlobalAuthorProfile`, `GlobalStrategy`, `GlobalModuleSettings`, `Industry`, `SeedKeyword` | `models.Model` | None (platform-wide) |
| **Account** | `Account`, `User`, `Plan`, `IntegrationSettings`, `ModuleEnableSettings`, `AISettings`, `AIPrompt`, `AuthorProfile`, `CreditBalance` | `AccountBaseModel` | `account` |
| **Site+Sector** | `Keywords`, `Clusters`, `ContentIdeas`, `Tasks`, `Content`, `Images`, `AutomationConfig` | `SiteSectorBaseModel` | `site`, `sector` |
---
## Global Models (`igny8_core/modules/system/global_settings_models.py`)
**Purpose:** Platform-wide defaults and API keys. Admin-only. NOT account-scoped.
### GlobalIntegrationSettings (Singleton)
```python
class GlobalIntegrationSettings(models.Model):
# OpenAI (used by ALL accounts)
openai_api_key = CharField(max_length=500)
openai_model = CharField(default='gpt-4o-mini')
openai_temperature = FloatField(default=0.7)
openai_max_tokens = IntegerField(default=8192)
# DALL-E / Image Generation
dalle_api_key = CharField(max_length=500)
dalle_model = CharField(default='dall-e-3')
dalle_size = CharField(default='1024x1024')
# Runware
runware_api_key = CharField(max_length=500)
```
**Critical:** Singleton (pk=1). API keys here are used by ALL accounts.
### GlobalAIPrompt
```python
class GlobalAIPrompt(models.Model):
prompt_type = CharField(max_length=100) # clustering, ideas, content_generation
prompt_value = TextField()
variables = JSONField(default=list)
is_active = BooleanField(default=True)
```
### GlobalAuthorProfile
```python
class GlobalAuthorProfile(models.Model):
name = CharField(max_length=255)
tone = CharField(max_length=50) # professional, casual, technical
language = CharField(max_length=10, default='en')
is_active = BooleanField(default=True)
```
--- ---