# UML Sequence Diagram: Generic Admin Mutation

Package flow: `backend.urls`, `api.urls.admin`, `api.views.admin`, `api.validator`, `api.utils`, `api.models`.

## Flow Description

1. Django routes `/api/admin/<resource>/<action>` to a concrete class in `api.views.admin`.
2. `AdminApiBase.initial()` authenticates the token, checks permissions, writes `IncomingApiAdmin`, and validates request envelope fields.
3. The concrete view validates its own payload with `BaseValidator`.
4. The view creates, updates, deletes, or reads model rows. Mutating views commonly update many-to-many join tables through helper methods.
5. Redis is synced when the changed entity participates in scheduler-facing cache data.
6. Kafka messages are sent when the timetabling microservice must mirror the change.
7. Audit rows are written and `api_response()` finalizes the response log.

```mermaid
sequenceDiagram
autonumber
participant FE as Frontend
participant URLs as backend.urls and api.urls.admin
participant Base as AdminApiBase
participant Auth as TokenAuthentication
participant Perm as CheckPermissionBackend
participant ApiLog as IncomingApiAdmin
participant View as Concrete admin view
participant Validator as BaseValidator
participant DB as Django models
participant Redis as bulk_sync_to_redis
participant Kafka as send_request
participant Audit as AuditTrailDetails

FE->>URLs: POST /api/admin/staff/update or similar
URLs->>Base: dispatch to view class
Base->>Auth: authenticate Authorization token
Auth-->>Base: user and token
Base->>Perm: user.has_perm(route_name)
Perm-->>Base: allowed or denied
Base->>ApiLog: insert incoming request log
Base->>Base: require timestamp and signature
Base->>View: call post(request)
View->>Validator: validate endpoint rules
Validator-->>View: ok or validation errors
View->>DB: mutate model rows and join tables
View->>Redis: insert/update/delete cache keys when required
View->>Kafka: publish microservice mirror message when required
View->>Audit: create audit detail rows
View->>Base: api_response(data)
Base->>ApiLog: update outgoing response log
Base-->>FE: normalized JSON envelope
```