78 lines
6.4 KiB
Markdown
78 lines
6.4 KiB
Markdown
# User Flow Overview
|
|
|
|
## Purpose
|
|
Describe the end-to-end journey from signup through planning, writing, automation, publishing, and billing within IGNY8, mapping each step to concrete backend/frontend modules so engineers can navigate without scanning code.
|
|
|
|
## Code Locations (exact paths)
|
|
- Auth & account: `backend/igny8_core/auth/{views.py,serializers.py,models.py,middleware.py}`, `frontend/src/store/authStore.ts`, routes in `frontend/src/App.tsx`
|
|
- Planner: `backend/igny8_core/modules/planner/views.py`, `business/planning/models.py`, `frontend/src/pages/Planner/*`
|
|
- Writer: `backend/igny8_core/modules/writer/views.py`, `business/content/models.py`, `frontend/src/pages/Writer/*`
|
|
- Automation: `backend/igny8_core/business/automation/{services/automation_service.py,tasks.py,views.py}`, `frontend/src/pages/Automation/AutomationPage.tsx`
|
|
- Publishing/Integration: `backend/igny8_core/business/integration/{models.py,services/integration_service.py}`, `modules/integration/views.py`, WordPress plugin endpoints consumed via `/api/v1/integration/`; `frontend/src/pages/Sites/*`
|
|
- Billing: `backend/igny8_core/business/billing/{models.py,services/credit_service.py,services/invoice_service.py,views.py}`, `frontend/src/pages/account/*`
|
|
- Tenancy enforcement: `backend/igny8_core/auth/middleware.py`, `backend/igny8_core/api/base.py`
|
|
|
|
## High-Level Responsibilities
|
|
- Authenticate users and attach account context to every request.
|
|
- Let users plan keywords/clusters/ideas, create tasks and content, optionally automate all seven pipeline stages.
|
|
- Manage sites/sectors and connect WordPress for publishing/sync.
|
|
- Track credits, plans, subscriptions, invoices, and payments through billing services.
|
|
|
|
## Detailed Behavior
|
|
- Signup/Login: `auth/views.py` issues JWTs; `AccountContextMiddleware` sets `request.account`; frontend `authStore` stores tokens and refreshes them.
|
|
- Planning: `KeywordViewSet`, `ClusterViewSet`, `ContentIdeasViewSet` create/list/update scoped by `SiteSectorModelViewSet` filters; frontend planner pages drive these endpoints.
|
|
- Writing: `TasksViewSet`, `ContentViewSet`, `ImagesViewSet` manage tasks/content/images; AI generation endpoints trigger Celery-backed functions.
|
|
- Automation: `AutomationViewSet` + `automation_service.py` orchestrate 7 stages (keywords→clusters→ideas→tasks→content→image-prompts→images/manual review) with pause/resume and credit estimation; Celery tasks `run_automation_task`/`resume_automation_task` execute runs.
|
|
- Publishing/Integration: `IntegrationViewSet` handles WP connection tests and sync; WP plugin sends/receives data via API key; content publish endpoints in writer module update WordPress via integration services.
|
|
- Billing: credit balances and costs computed in `credit_service.py`; invoices via `invoice_service.py`; payments via `payment_service.py`; endpoints in `modules/billing/views.py` feed frontend billing pages.
|
|
|
|
## Data Structures / Models Involved (no code)
|
|
- Tenancy: `Account`, `Site`, `Sector` (plus `SiteUserAccess`), base models `AccountBaseModel`/`SiteSectorBaseModel`.
|
|
- Planning: `Keywords`, `Clusters`, `ContentIdeas`.
|
|
- Writing: `Tasks`, `Content`, `Images`.
|
|
- Automation: `AutomationConfig`, `AutomationRun`.
|
|
- Billing: `CreditTransaction`, `CreditUsageLog`, `CreditCostConfig`, `Invoice`, `Payment`, `CreditPackage`, `Subscription`, `Plan`.
|
|
- Integration: `SiteIntegration`.
|
|
|
|
## Execution Flow
|
|
1) User signs in → JWT stored → `AccountContextMiddleware` populates `request.account`.
|
|
2) Tenant creates sites/sectors (`SiteViewSet`), selects industry/sectors, optionally connects WordPress.
|
|
3) Planner: upload/enter keywords → cluster → generate ideas (manual or via automation/AI functions).
|
|
4) Writer: create tasks from ideas, generate content/images (manual endpoints or automation stages).
|
|
5) Publish: send to WordPress via integration endpoints or automation publish step; WP plugin syncs back statuses.
|
|
6) Automation (optional): run 7-stage pipeline via `AutomationViewSet` + Celery tasks; pause/resume supported.
|
|
7) Billing: credits deducted per AI/pipeline usage (`credit_service`), invoices/payments recorded; users view in billing pages.
|
|
|
|
## Cross-Module Interactions
|
|
- Automation invokes planner/writer endpoints/services and logs credit estimates.
|
|
- Billing hooks into automation and writer AI calls via credit deduction utilities.
|
|
- Integration uses site/account context and WP API key for sync; writer publish flows depend on integration configuration.
|
|
|
|
## State Transitions (if applicable)
|
|
- Account status (`active/suspended/trial/cancelled`) governs access; plan/subscription affect limits.
|
|
- Tasks/content/images status transitions handled in writer endpoints; automation run status moves through `created/running/paused/completed/failed`.
|
|
- Site activation via `set_active`; sectors toggled via `select_sectors`.
|
|
|
|
## Error Handling
|
|
- Unified API responses via `api/response.py`; DRF exception handler configured in settings; frontend shows toasts/banners.
|
|
- Automation errors logged via `automation_logger`; tasks wrapped in Celery with retries where defined.
|
|
|
|
## Tenancy Rules
|
|
- `AccountContextMiddleware` sets `request.account`; base viewsets filter by account/site/sector; API key auth sets account from `Site.wp_api_key`; public site slug reads limited to active sites.
|
|
|
|
## Billing Rules (if applicable)
|
|
- AI/automation uses `CreditService.deduct_credits_for_action`; credit balance required before runs; plans/subscriptions define included credits and sector/site limits.
|
|
|
|
## Background Tasks / Schedulers (if applicable)
|
|
- Celery tasks: automation runs (`run_automation_task`, `resume_automation_task`), scheduler `check_scheduled_automations`, AI functions (`ai/tasks.py`), publishing tasks (`tasks/wordpress_publishing.py`).
|
|
|
|
## Key Design Considerations
|
|
- Strong tenant isolation via middleware + filtered querysets.
|
|
- Automation relies on polling and Celery; frontend automation page polls every 5s during runs.
|
|
- Billing is authoritative in backend; frontend is read-only except initiating purchases/subscriptions.
|
|
|
|
## How Developers Should Work With This Module
|
|
- Trace user-visible flows by following router → page component → service call → backend viewset.
|
|
- When adding steps, ensure credit deductions and tenancy filters are applied in the corresponding backend service/viewset.
|
|
- Keep WP integration changes consistent with API key auth and `SiteIntegration` schema.
|