Architecture: Traditional SaaS (single PostgreSQL database, row-level access control via role and visibility columns).
Reference app: GP Booking App (patterns: Django 5.2, DRF, gunicorn, celery, mozilla-django-oidc, grappelli, docker-compose).
Key difference from GP Booking App: No SiaaS multi-tenancy (no TenantMiddleware, no SectorDatabaseRouter, no per-client databases). Single Keycloak realm ixg.
¶ Brand Configuration
ixg-green: #1A3D2B
ixg-gold: #B07D0E
ixg-light: #F7F6F2
ixg-dark: #1A1A1A
Objective: Django project scaffold, Docker environment, PostgreSQL database schema, authentication.
- Django 5.2 project at
/root/work/ixg_platform/
- Core packages: DRF, django-filter, django-environ, grappelli, cors-headers, gunicorn, psycopg2-binary, celery
- OIDC: mozilla-django-oidc
- AI/encryption: openai, google-genai, django-encrypted-model-fields, cryptography
docker-compose.yml: app (gunicorn), celery_worker, celery_beat, postgres:15-alpine, redis:7-alpineDockerfile: python:3.11-slimscripts/entrypoint.sh: wait-for-db → migrate → collectstatic → gunicorn- Host nginx reverse proxy at
/etc/nginx/sites-enabled/ixg
| # |
Model |
Table |
App |
| 1 |
User |
users |
users |
| 2 |
Subscription |
subscriptions |
subscriptions |
| 3 |
ProcessingBatch |
processing_batches |
batches |
| 4 |
QCResult |
qc_results |
qc |
| 5 |
CertificateOfAnalysis |
certificates_of_analysis |
documents |
| 6 |
RegulatoryCert |
regulatory_certs |
documents |
| 7 |
Shipment |
shipments |
shipments |
| 8 |
Document |
documents |
documents |
| 9 |
CAPARecord |
capa_records |
capa |
| 10 |
ESGFieldReport |
esg_field_reports |
esg |
| 11 |
AIInteraction |
ai_interactions |
ai |
| 12 |
Notification |
notifications |
notifications |
| 13 |
AgentConfig |
agent_configs |
ai |
mozilla-django-oidc with custom KeycloakOIDCBackend- Single Keycloak realm
ixg at http://194.164.95.50:8443
- OIDC creates/updates User from claims (email, name, role)
- RBACMiddleware for role-based route access (admin→/admin/, ops→/ops/, buyer→/portal/)
- Custom User model: email-based, UUID PK, roles: buyer/ops/admin
- Grappelli admin skin
- All 13 models registered in admin
- AgentConfig management at
/admin/ai/agentconfig/
Objective: CRUD APIs for all business entities.
GET/POST/PUT/DELETE /api/batches/- Auto-generate batch reference
- Filter by status, grade; search by reference
- Pagination (20/page), ordering
GET/POST/PUT/DELETE /api/qc-results/- Create QC result → auto-calculate overall_pass
- On failure: auto-create CAPA record
GET/POST/PUT/DELETE /api/shipments/
POST /api/documents/upload/ — file upload with type/visibilityGET /api/documents/ — list with buyer visibility filtering- File storage:
/data/ixg-documents/{batch_id}/{filename}
GET/POST/PUT/DELETE /api/capa-records/GET/POST/PUT/DELETE /api/esg-reports/
Objective: Operations dashboard and management interface at /ops/.
- Sidebar navigation (Dashboard, Batches, QC Results, Shipments, CAPA Records, Documents, ESG Reports)
- KPI cards: QC pass/fail counts, active shipments, open CAPAs
- Recent batches table, recent QC results, unread notifications
- Batches: list with search/filter (status, grade) + detail (related QC, shipments, CAPAs, documents)
- QC Results: list with pass/fail filter + detail view
- Shipments: list with status filter + detail view
- CAPA Records: list with status filter + detail view (root cause, corrective/preventive actions)
- Documents: list with type filter
- ESG Reports: list
Templates: 11 templates in templates/ops/ (base_ops.html + 10 pages)
Objective: Buyer-facing dashboard and management interface at /portal/.
- Green theme sidebar (Dashboard, Batches, Documents, Subscription, AI Chat)
- KPI cards: total batches, active shipments, recent documents
- List with search/filter by status
- Detail with shipments timeline, documents, ESG reports
- List filtered by buyer visibility
- Filter by document type
- Batch reference displayed
- Plan name, status badge, current period, created date
Objective: AI chatbot, agent management, chat UI.
- AgentConfig model: name, provider (OpenAI/DeepSeek/Google/Ollama/Custom), encrypted API key storage, system prompt, temperature, max_tokens, capabilities
- Agent service: multi-provider dispatch via
AgentService.execute_prompt()
- Chat API:
POST /api/ai-interactions/chat/ — accepts agent_id, message, session_id, history
- Agent admin:
/admin/ai/agentconfig/ for creating/configuring agents
- Standalone chat UI:
/portal/chat/ — agent selector, session management, Markdown rendering
- Embeddable widget:
/portal/chat/embed/ — iframe-ready with ?agent_id=X
- Default agent: "IXG Assistant" — DeepSeek, configured and active
- Dependencies: openai, google-genai, django-encrypted-model-fields, cryptography
¶ Phase 6: Outstanding
¶ P99 — Outstanding Tasks
Chat UI: Chat API works with token auth; browser session cookie auth needs debugging for the chat page JS fetch.
Email notifications: SMTP outgoing (QC fail alerts, shipment updates, CAPA assignments) + IMAP incoming (certificate PDF auto-import). Requires domain + email hosting (Fasthosts like GP Booking App) or transactional API (SendGrid/Mailgun).
Compliance automation: ✅ implemented (P99C, deployed 05 Aug 2026).
- CoA controlled workflow (P99C.1): versioned product specification table (Unrefined Shea Butter v1.0: FFA ≤3%, moisture ≤0.1%, peroxide ≤10 meq O2/kg, visual A/B/C); structured QC results with methods; four-eyes QC verification (submitter cannot self-approve); auto-generated IXG Quality Summary PDF (reportlab, SHA-256 hashed) only after quality approval; original independent lab PDF retained as authoritative source; commercial release approval publishes to buyers + notification.
- EUDR due diligence (P99C.2): Facility, OriginZone (geo + verification), CollectorGroup, HarvestIntake, IntakeBatchLineage, EUDREvidence, RiskAssessment, MitigationAction, DueDiligenceCase, DueDiligenceStatementReference; rule-based completeness check + risk assessment (no AI legal conclusions); named compliance approval; manual external submission (DDS reference recorded). Shea butter not in EUDR Annex I — tracker is buyer-assurance evidence, flagged in UI.
- UI: Ops portal QC Approvals / CoA Reviews / EUDR Compliance; buyer portal /portal/compliance.
- APIs: /api/product-specs/, /api/facilities/, /api/origin-zones/, /api/collector-groups/, /api/harvest-intakes/, /api/intake-batch-lineage/, /api/eudr-cases/, /api/eudr-evidence/, /api/risk-assessments/, /api/mitigation-actions/, /api/dds-references/, /api/qc-results/{id}/verify/, /api/certificates-of-analysis/{id}/approve/.
Polish: UI refinement, form validation, error handling, loading states across both portals.
| Aspect |
GP Booking App (SiaaS) |
IXG Platform (SaaS) |
| Database |
Multi-DB per client |
Single PostgreSQL |
| Tenancy |
Subdomain-based TenantMiddleware |
Role/visibility row-level |
| Auth |
Multi-realm Keycloak |
Single ixg realm |
| User model |
CustomUser (AbstractUser) |
User (AbstractUser) |
| Auth backend |
OIDC + CrossClient |
OIDC + ModelBackend |
| File storage |
Per-client |
Central /data/ixg-documents/ |
| Encryption |
django-encrypted-model-fields |
Same (API keys, email creds) |
| AI agents |
integrations_agentconfig |
ai.AgentConfig (same pattern) |
| Frontend |
Django templates + DRF |
Django templates + DRF |
- Mission Summary:
/root/work/ixg_platform/SESSION_CHECKPOINT.md (on VPS)
- Source Code:
/root/work/ixg_platform/ (on VPS)
- Wiki: This wiki (home/development/plan)