architecture-and-logic-audit

name	architecture-and-logic-audit
description	Use when Codex needs to evaluate architecture, business logic, authorization, validation, data flow, module boundaries, or P0/P1/P2/P3 risks in this repo.

Architecture And Logic Audit

Goal

Evaluate whether the current architecture and business logic are coherent, secure, maintainable, and aligned with the product domains. Produce prioritized findings without changing code.

When to use

Use this skill when the user asks for architecture review, logic audit, permission review, validation review, data-flow review, module boundary review, or risk classification.

Run project-intake-map first if the project map is missing or stale.

Required steps

1. Read the latest docs/audits/project-intake-map.md if it exists; otherwise build enough local context from routes, URLs, models, and core services.
2. Inspect high-signal files:
   • frontend/src/app/routes.tsx
   • frontend API clients and hooks
   • backend/web3d/api/urls.py, backend/web3d/urls.py
   • Django app models, API views, services, permissions, tests
3. Trace critical user flows end to end:
   • auth and roles
   • student learning and quiz attempt
   • classroom assignment and grading
   • gamification/leaderboard/notifications
   • admin/backoffice operations
   • payments/support/content governance when relevant
4. Evaluate architecture:
   • module ownership and coupling
   • duplicated logic across frontend/backend
   • service boundaries and side effects
   • sync vs async work on request paths
   • error handling and observability
5. Evaluate business logic:
   • invariants and state transitions
   • role-based permissions
   • validation consistency between frontend and backend
   • idempotency and dedupe keys for event workflows
   • race conditions and partial-update risks
6. Evaluate tests:
   • whether important flows have regression coverage
   • whether tests assert permissions, validation, and edge cases
7. Classify every issue:
   • P0: data loss, security bypass, production outage, payment/auth breach
   • P1: incorrect business outcome, broken core flow, severe maintainability risk
   • P2: medium-risk logic gap, missing guardrail, likely future bug
   • P3: cleanup, clarity, documentation, minor consistency issue
8. Write the report in Vietnamese to docs/audits/architecture-and-logic-audit.md.

Output format

Write a Vietnamese Markdown report with:

1. Pham vi da doc
2. Tom tat kien truc
3. Danh gia logic nghiep vu
4. Danh gia phan quyen va validation
5. Danh gia luong du lieu
6. Phat hien P0/P1/P2/P3
7. Bang chung
8. Khuyen nghi uu tien
9. Cau hoi con mo

Each finding must include: priority, evidence path/route/API/model, impact, recommendation, and confidence.

Quality checklist

• Findings lead with risks, not summaries.
• Every finding has concrete evidence from the repo.
• Authorization and validation are evaluated separately.
• Business invariants are stated explicitly.
• The report separates confirmed issues from hypotheses.

Safety rules

• Stay read-only unless the user explicitly asks for implementation.
• Do not change code, migrations, data, generated bundles, or configuration.
• Do not run destructive commands, deploys, uploads, resets, or production jobs.
• Do not expose secrets or copy private data into the report.
• If dynamic verification is needed, use local/dev only and state the command before running it.