apps.md

# SaaS Platform — Apps Inventory

> **10 Django apps** · Source of truth: `AGENT.md` · Config: `config/settings/__init__.py`

---

## Architecture

```
core → apps → domains   (one-way, no reverse)
```

| Layer | Purpose |
|-------|---------|
| `config/` | Runtime wiring (settings, urls, jinja2) |
| `core/` | Infrastructure glue (base models, middleware, permissions, utils) |
| `apps/` | 10 SaaS platform apps |
| `domains/` | Pluggable business modules (empty — future verticals) |
| `services/` | Background execution (email, maintenance, monitoring, scheduling) |

---

## 1. `apps/accounts` — Identity & Lifecycle

**Phase 1** · Registration, login, email verification, password management, profiles, OAuth.

### Models (7)

| Model | File |
|-------|------|
| User | `models/user.py` |
| Credentials | `models/credentials.py` |
| PasswordHistory | `models/password_history.py` |
| EmailVerification | `models/email_verification.py` |
| PasswordReset | `models/password_reset.py` |
| Profile | `models/profile.py` |
| LoginHistory | `models/login_history.py` |

### Services (2)

| Service | File | Functions |
|---------|------|-----------|
| Auth Service | `services/auth_service.py` | ~19 (register, login, verify, reset, change password/email, profile) |
| OAuth Service | `services/oauth_service.py` | Google + GitHub OAuth flow |

### Config Dependencies

| Setting | Value |
|---------|-------|
| `AUTH_USER_MODEL` | `accounts.User` |
| `LOGIN_URL` | `/login/` |
| `LOGIN_REDIRECT_URL` | `/dashboard/` |
| `LOGOUT_REDIRECT_URL` | `/` |
| `EMAIL_VERIFICATION_EXPIRY_HOURS` | `1` |
| `PASSWORD_RESET_EXPIRY_HOURS` | `1` |
| `NOTIFY_NEW_DEVICE_LOGIN` | `True` |
| `OAUTH_GOOGLE_CLIENT_ID` | (from settings) |
| `OAUTH_GITHUB_CLIENT_ID` | (from settings) |

---

## 2. `apps/security` — Threat Protection

**Phase 2** · MFA, sessions, token rotation, rate limiting, trusted devices, security events.

### Models (8)

| Model | File |
|-------|------|
| Session | `models/session.py` |
| RefreshToken | `models/refresh_token.py` |
| TokenBlacklist | `models/token_blacklist.py` |
| MFAFactor | `models/mfa_factor.py` |
| BackupCode | `models/backup_code.py` |
| TrustedDevice | `models/trusted_device.py` |
| SecurityEvent | `models/security_event.py` |
| RateLimit | `models/rate_limit.py` |

### Services (6)

| Service | File |
|---------|------|
| Session Service | `services/session_service.py` |
| MFA Service | `services/mfa_service.py` |
| Rate Limit Service | `services/rate_limit_service.py` |
| Alert Service | `services/alert_service.py` |
| Event Service | `services/event_service.py` |
| JWT Service | `services/jwt_service.py` |

### Config Dependencies

| Setting | Value |
|---------|-------|
| `JWT_SECRET_KEY` | (from env, fallback to SECRET_KEY) |
| `JWT_ALGORITHM` | `HS256` |
| `JWT_ACCESS_EXPIRY_MINUTES` | `60` |

---

## 3. `apps/access` — RBAC Authorization

**Phase 3** · Roles, permissions, role-permission mapping, authorization middleware.

### Models (4)

| Model | File |
|-------|------|
| Role | `models/role.py` |
| Permission | `models/permission.py` |
| RolePermission | `models/role_permission.py` |
| UserRole | `models/user_role.py` |

### Services (2)

| Service | File | Functions |
|---------|------|-----------|
| RBAC Service | `services/rbac_service.py` | 16 (create/assign/revoke roles & permissions, check_access) |
| Role Seed Service | `services/role_seed_service.py` | Default role seeding |

### Additional Files

- `decorators.py` — `@require_role`, `@require_permission`
- `middleware.py` — Request-level access guard

---

## 4. `apps/organizations` — Multi-Tenancy

**Phase 4** · Organizations, memberships, API keys, feature flags, storage quotas, tenant isolation.

### Models (13)

| Model | File |
|-------|------|
| Organization | `models/organization.py` |
| OrgMembership | `models/membership.py` |
| OrgRole | `models/org_role.py` |
| OrgInvitation | `models/invitation.py` |
| OrgSettings | `models/org_settings.py` |
| FeatureFlag | `models/feature_flag.py` |
| APIKey | `models/api_key.py` |
| ServiceToken | `models/service_token.py` |
| File | `models/file.py` |
| StorageQuota | `models/storage_quota.py` |
| UsageMetric | `models/usage_metric.py` |
| QuotaCounter | `models/quota_counter.py` |
| SocialAccount | `models/social_account.py` |

### Services (6)

| Service | File |
|---------|------|
| Org Service | `services/org_service.py` |
| Membership Service | `services/membership_service.py` |
| API Key Service | `services/api_key_service.py` |
| Feature Flag Service | `services/feature_flag_service.py` |
| File Service | `services/file_service.py` |
| Quota Service | `services/quota_service.py` |

### Config Dependencies

| Setting | Value |
|---------|-------|
| `BASE_DOMAIN` | `localhost:9000` |
| `SESSION_COOKIE_DOMAIN` | `.localhost` |
| `CSRF_COOKIE_DOMAIN` | `.localhost` |
| `DEFAULT_BUSINESS_TYPES` | `["E-Commerce", "Agency", "Retail", "Other"]` |

---

## 5. `apps/audit` — Compliance & GDPR

**Phase 5** · Consent tracking, data export, soft delete, PII audit, deletion locks.

### Models (5)

| Model | File |
|-------|------|
| ConsentRecord | `models/consent_record.py` |
| DataExport | `models/data_export.py` |
| Deletion | `models/deletion.py` |
| DeletionLock | `models/deletion_lock.py` |
| PIIAccessLog | `models/pii_access_log.py` |

### Services (1)

| Service | File | Functions |
|---------|------|-----------|
| Compliance Service | `services/compliance_service.py` | 14 (consent, export, delete, PII access, locks) |

### Config Dependencies

| Setting | Value |
|---------|-------|
| `TERMS_OF_SERVICE_VERSION` | `1.0` |

---

## 6. `apps/notifications` — Communications

**Phase 2 + 7** · Email, SMS, push, in-app notifications with user preferences.

### Models (2)

| Model | File |
|-------|------|
| NotificationPreference | `models/preference.py` |
| NotificationTemplate | `models/template.py` |

### Services (2)

| Service | File |
|---------|------|
| Dispatch Service | `services/dispatch_service.py` (18 functions) |
| SMS Provider | `services/sms_provider.py` (Twilio REST adapter) |

### Config Dependencies

| Setting | Value |
|---------|-------|
| `EMAIL_BACKEND` | `django.core.mail.backends.filebased.EmailBackend` |
| `EMAIL_FILE_PATH` | `BASE_DIR / 'emails'` |
| `DEFAULT_FROM_EMAIL` | `noreply@saas.local` |
| `NOTIFY_NEW_DEVICE_LOGIN` | `True` |

---

## 7. `apps/intelligence` — AI & Security Intelligence

**Phase 6** · Activity logging, risk scoring, anomaly detection, LLM chat, content moderation.

### Models (5+)

| Model | File |
|-------|------|
| EventLog | `models/event_log.py` |
| AIModel | `models/ai_model.py` |
| AIPrompt | `models/ai_prompt.py` |
| ChatSession / ChatMessage | `models/chat.py` |
| RiskScore / Anomaly / Metric / ContentEmbedding / etc. | `models/analytics.py` |

### Services (5)

| Service | File |
|---------|------|
| Event Service | `services/event_service.py` |
| Analytics Service | `services/analytics_service.py` (risk scoring, anomaly detection, vector search) |
| AI Service | `services/ai_service.py` (LLM integration, RAG pipeline) |
| Moderation Service | `services/moderation_service.py` |
| Personalization Service | `services/personalization_service.py` |

---

## 8. `apps/operations` — Enterprise Operations

**Phase 7** · Audit logs, admin ops, webhooks, maintenance mode, system settings, jobs.

### Models (5)

| Model | File |
|-------|------|
| AuditLog / AdminAction | `models/audit.py` |
| SystemSetting / BackgroundJob | `models/system.py` |
| Webhook / WebhookDelivery | `models/webhook.py` |
| Deployment | `models/deployment.py` |
| Notification | `models/notification.py` |

### Services (4)

| Service | File |
|---------|------|
| Admin Ops Service | `services/admin_ops_service.py` (force reset, impersonation, revoke sessions) |
| Operations Service | `services/operations_service.py` (maintenance mode, emergency lock, system settings) |
| Webhook Service | `services/webhook_service.py` (HMAC + replay protection) |
| Idempotency Service | `services/idempotency_service.py` |

### Config Dependencies

| Setting | Value |
|---------|-------|
| `Q_CLUSTER.name` | `saas_cluster` |
| `Q_CLUSTER.workers` | `2` |
| `Q_CLUSTER.timeout` | `60` |

---

## 9. `apps/billing` — Monetization & Razorpay

**Phase 8** · Subscription plans, org subscriptions, payment history, Razorpay integration.

### Models (3)

| Model | File |
|-------|------|
| SubscriptionPlan | `models.py` |
| OrganizationSubscription | `models.py` |
| BillingHistory | `models.py` |

### Services (3)

| Service | File |
|---------|------|
| Billing Service | `services/billing_service.py` |
| Plan Enforcement Service | `services/plan_enforcement.py` |
| Razorpay Service | `services/razorpay_service.py` |

### Config Dependencies

| Setting | Value |
|---------|-------|
| `RAZORPAY_KEY_ID` | (from `.env`) |
| `RAZORPAY_KEY_SECRET` | (from `.env`) |
| `RAZORPAY_CURRENCY` | `INR` |

---

## 10. `apps/dashboard` — UI Aggregator

**No Phase** · Authenticated landing page. Pulls data from accounts, organizations, and other apps.

- **Models**: None
- **Services**: None
- **Views**: `views.py` — dashboard index

---

## Background Services (`services/`)

| Service | File | Purpose |
|---------|------|---------|
| Email | `email/email_service.py` | Async email sending with template rendering and retry |
| Maintenance | `maintenance/maintenance_service.py` | Token cleanup, scheduled purge, data retention |
| Monitoring | `monitoring/monitoring_service.py` | Health checks, metrics aggregation |
| Scheduling | `scheduling/scheduling_service.py` | Job queue, retry policy, dead-letter handling |

---

## Core Layer (`core/`)

| Module | Files | Purpose |
|--------|-------|---------|
| `models/` | `base.py`, `tenant_mixin.py` | TimestampedModel, SoftDeleteModel, TenantScopedModel |
| `middleware/` | 6 files | JWT, subdomain, tenant, security, authorization, request_id |
| `permissions/` | `base.py`, `decorators.py`, `security_decorators.py` | `@require_role`, `@require_permission`, `@stepup_auth_required` |
| `utils/` | 6 files | circuit_breaker, pii_registry, privacy, password_breach, ip, slug |
| `exceptions/` | `base.py` | Custom exception classes |
| `filters/` | `pii_filters.py` | `mask_email`, `mask_phone`, `mask_name`, `mask_ip` |
| `services/` | `encryption.py` | Encryption utilities |

---

## Middleware Pipeline (13 layers, order matters)

| # | Middleware | Source |
|---|-----------|--------|
| 1 | SecurityMiddleware | Django built-in |
| 2 | RequestIDMiddleware | `core.middleware.request_id` |
| 3 | SessionMiddleware | Django built-in |
| 4 | CommonMiddleware | Django built-in |
| 5 | CsrfViewMiddleware | Django built-in |
| 6 | AuthenticationMiddleware | Django built-in |
| 7 | JWTMiddleware | `core.middleware.jwt_middleware` |
| 8 | SubdomainMiddleware | `core.middleware.subdomain_middleware` |
| 9 | RateLimitMiddleware | `core.middleware.security` |
| 10 | TenantContextMiddleware | `core.middleware.tenant` |
| 11 | AuthorizationMiddleware | `core.middleware.authorization` |
| 12 | MessageMiddleware | Django built-in |
| 13 | XFrameOptionsMiddleware | Django built-in |