docs re-org

docs/90-ARCHIVED/master-docs-original/20-api/ENDPOINTS/accounts.md

@@ -0,0 +1,56 @@
+# Account Endpoints
+
+## Purpose
+Document account management endpoints for settings, team management, and usage analytics.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/api/urls.py`
+- Views: `backend/igny8_core/api/account_views.py`
+- Settings/tenancy middleware: `backend/igny8_core/auth/middleware.py`
+
+## High-Level Responsibilities
+- Provide account settings retrieval/update, team member management, and usage analytics summaries for the authenticated account.
+
+## Detailed Behavior
+- Base path: `/api/v1/account/`
+- Settings:
+  - `GET /api/v1/account/settings/` → returns account settings (ViewSet `retrieve`).
+  - `PATCH /api/v1/account/settings/` → partial update of account settings.
+- Team:
+  - `GET /api/v1/account/team/` → list team members.
+  - `POST /api/v1/account/team/` → create/add a team member.
+  - `DELETE /api/v1/account/team/<id>/` → remove a team member.
+- Usage analytics:
+  - `GET /api/v1/account/usage/analytics/` → returns usage analytics overview (implementation in `UsageAnalyticsViewSet.overview`).
+- Permissions/tenancy: views expect authenticated users; account context from middleware; data scoped to `request.account`.
+
+## Data Structures / Models Involved (no code)
+- Account, User, and related analytics data as computed in account views.
+
+## Execution Flow
+- Requests hit `account_views` ViewSets; account context derived from session/JWT via middleware; view methods return unified responses.
+
+## Cross-Module Interactions
+- Usage analytics may summarize module usage (planner/writer/etc.) depending on `UsageAnalyticsViewSet` implementation.
+
+## State Transitions
+- Account settings updates; team membership changes.
+
+## Error Handling
+- Standard unified responses for validation/auth errors; 404 when deleting non-existent team members.
+
+## Tenancy Rules
+- All endpoints scoped to authenticated user’s account; no cross-tenant access.
+
+## Billing Rules
+- None directly; account limits and credits are exposed via billing endpoints.
+
+## Background Tasks / Schedulers
+- None.
+
+## Key Design Considerations
+- Non-router endpoints used for simplicity; still leverage DRF ViewSet actions.
+
+## How Developers Should Work With This Module
+- Keep settings/team/usage endpoints under `/api/v1/account/`; ensure account context is required for all operations.
+