CepatEdge

Appearance

AI Audit Workflow ​

This document defines the standard audit workflow for AI agents reviewing the backend system.

It ensures that system architecture, services, caches, validation, and security remain stable over time.

Agents must follow this workflow whenever performing a system audit.

Audit Folder Structure ​

All AI audit results must follow the structure below.

docs/audits
├── WORKFLOW.md
├── reports
│   └── audit-YYYY-MM-DD[a-z].md
└── summary
    ├── system.md
    └── cache.md

reports/ ​

Contains full audit reports.

Each audit run creates a new file:

audit-YYYY-MM-DDa.md
audit-YYYY-MM-DDb.md
audit-YYYY-MM-DDc.md

Use the next alphabetical suffix if multiple audits occur on the same day.

Examples:

audit-2026-03-15a.md
audit-2026-03-15b.md
audit-2026-03-16a.md

These files contain the complete audit output.

Reports are never modified after creation.

They represent historical audit records.

summary/ ​

Contains latest system state summaries.

Each file represents a specific domain.

Examples:

system.md
cache.md
security.md
services.md

Summaries always reflect the latest audit results.

Summaries must reference the latest report file.

Example reference format:

Latest audit report: ../reports/audit-2026-03-15a.md

If a new domain is introduced (for example a new subsystem), the agent may create a new summary file.

Example:

summary/storage.md
summary/queues.md
summary/analytics.md

Audit Execution Workflow ​

Agents must follow the steps below when performing a system audit.

Step 1 — Understand System Architecture ​

Before scanning code, the agent must review system documentation.

Important locations:

docs/architecture
docs/security
docs/workflows
docs/institutional-readiness

The agent must understand:

  • service architecture
  • cache architecture
  • permission system
  • authentication flow
  • database structure

Only after understanding the architecture should the audit begin.

Step 2 — Type System Integrity ​

Inspect:

apps/worker/src/types

Verify:

  • domain types are centralized
  • services reuse central types
  • response types match route responses
  • database schema aligns with domain types

Report any type drift or duplication.

Step 3 — Zod Validation Integrity ​

Inspect:

apps/worker/src/lib/zod

Verify:

  • every route input has validation
  • schemas match service expectations
  • schemas are reused where appropriate
  • unsafe input cannot bypass validation

Report missing or overly permissive schemas.

Step 4 — Service Layer Integrity ​

Inspect:

apps/worker/src/lib/services

Verify that:

  • business logic exists only in services
  • services enforce permissions
  • services use shared utilities
  • services do not duplicate logic

Routes must not contain business logic.

Step 5 — Route Layer Integrity ​

Inspect:

apps/worker/src/routes

Routes must only:

  • validate input
  • call services
  • format responses

Routes must not:

  • access database directly
  • implement business logic
  • bypass services

Report any violations.

Step 6 — Cache Consistency Audit ​

Inspect cache services:

apps/worker/src/lib/services/cache

Verify:

  • cache keys are deterministic
  • cache hit returns stable data structures
  • cache miss triggers DB fallback
  • mutation operations invalidate relevant caches

Check for:

  • stale cache risks
  • inconsistent cache key generation
  • bypassing cache layer
  • race conditions during cache writes

All user reads must pass through the user cache service.

Report any cache desynchronization risks.

Step 7 — Security Audit ​

Analyze:

  • authentication logic
  • JWT validation
  • session verification
  • permission enforcement
  • route protection
  • IDOR risks
  • input validation
  • cookie configuration
  • CORS configuration
  • secret usage

Report confirmed vulnerabilities only.

Avoid speculative findings.

Step 8 — Observability and Auditing ​

Inspect monitoring systems:

services/audit
services/monitoring
services/internal

Recommend logging where necessary.

Examples:

  • critical mutations should create audit logs
  • suspicious authentication attempts should be logged
  • cache anomalies should be monitored

Step 9 — Test Coverage Review ​

Inspect:

src/__tests__
src/lib/services/*/__tests__
src/routes/__tests__

Verify coverage for:

  • authentication
  • services
  • cache behavior
  • routes

Report missing critical tests.

Step 10 — Attack Simulation ​

Simulate possible attacks:

  • privilege escalation
  • IDOR
  • cache poisoning
  • stale cache exploitation
  • authentication bypass

Document realistic attack scenarios.

Step 11 — Generate Full Audit Report ​

Write a new report file:

docs/audits/reports/audit-YYYY-MM-DD[a-z].md

The report must include:

  • architecture integrity
  • type system issues
  • validation issues
  • cache risks
  • security findings
  • observability gaps
  • test coverage gaps
  • recommendations

Reports must never overwrite previous reports.

Step 12 — Update Summaries ​

After creating the report, update the relevant summary files.

Example:

docs/audits/summary/system.md
docs/audits/summary/cache.md

Each summary must include:

Latest audit report reference
Current system health status
Outstanding issues
Resolved issues
Key recommendations

Summaries represent the current system state.

Adding New Audit Domains ​

If the system introduces a new subsystem (for example queues, analytics, or storage), the agent may create a new summary file.

Example:

docs/audits/summary/storage.md
docs/audits/summary/analytics.md

When this happens the agent must:

  1. Notify the developer
  2. Recommend adding the subsystem to this workflow

This ensures future audits include the new system component.

Important Rules ​

Agents must follow these rules:

  • Never modify historical audit reports
  • Always generate a new report file
  • Summaries must reflect the latest report
  • Do not modify architecture docs unless instructed
  • Only report confirmed issues
  • Respect the system's architectural design

Goal of This Workflow ​

This workflow ensures that:

  • system architecture remains consistent
  • cache systems stay reliable
  • security risks are detected early
  • audit history is preserved
  • AI agents can safely review the system over time

This creates a continuous architecture and security review system for the project.