# Universal Chartered Accountant Professional AI Agent — System Architecture

This is a modular architecture for a website-deployed AI agent that behaves like an expert Chartered Accountant across audit, tax, accounting, forensic, due-diligence, and advisory work — built so that **law, rates, and standards live in an updateable knowledge layer, never hard-coded into the reasoning prompt.**

## Why it's split this way

The single biggest risk in a system like this is a static prompt that quietly goes stale — a GST rate, a TDS threshold, a due date frozen at whatever was true the day the prompt was written, presented with the same confidence a year later when it's wrong. This architecture separates:

- **What almost never changes** — how to reason like a CA, what evidence to look for, what the audit lifecycle is, how to structure a tax memo. → `01-core/`
- **What changes constantly** — actual rates, thresholds, deadlines, notification text. → `02-knowledge-layer/`, injected at request time, never baked into the core prompt.
- **Domain reasoning scaffolds** that sit between the two — audit/tax/accounting logic that references the knowledge layer for numbers but doesn't contain them itself. → `03-`, `04-`
- **Output templates** — the documents a CA actually produces. → `05-document-engine/`
- **Verification** that the whole thing behaves and holds up under pressure. → `06-testing-redteam/`
- **How it actually gets wired into your website.** → `integration/`

## File map

```
01-core/
  system-prompt.md         ← the actual text to send as the Claude API `system` parameter
  reasoning-workflow.md     ← human-facing explainer + worked example (not sent to the model)

02-knowledge-layer/
  schema.md                 ← knowledge entry + changelog schema, injection format, staleness rules
  knowledge-index.example.json  ← example entries (STATIC vs. FREQUENT contrast) — replace with real data
  update-protocol.md        ← what `UPDATE KNOWLEDGE` / `CHECK FOR CHANGES` actually require, chat-side and backend-side

03-audit-engine/
  audit-copilot.md          ← full audit lifecycle, assertion mapping, real-world scenario playbook

04-tax-accounting-engine/
  tax-advisory.md            ← direct/indirect/international tax fact-gathering and response discipline
  financial-reporting.md     ← Ind AS/AS recognition-measurement-disclosure discipline, high-risk areas

05-document-engine/
  document-templates.md      ← working papers, MRL, audit program, technical memo, DD findings, etc.

06-testing-redteam/
  test-cases.md               ← functional behaviour tests
  redteam-checklist.md        ← adversarial/injection/pressure tests

integration/
  website-integration.md      ← how to wire this into your website's Claude API backend
```

## How the pieces combine at request time

```
 ┌─────────────────────────┐
 │ 01-core/system-prompt.md│  →  sent as `system` (static, cached)
 └─────────────────────────┘
              +
 ┌─────────────────────────┐
 │ <client_context>         │  →  this session's engagement facts (never cross-client)
 └─────────────────────────┘
              +
 ┌─────────────────────────┐
 │ <knowledge_context>       │  →  retrieved from 02-knowledge-layer per query, with source/date
 └─────────────────────────┘
              +
 ┌─────────────────────────┐
 │ user's actual question    │
 └─────────────────────────┘
              ↓
        Claude API call
              ↓
   response, reasoning through
   FACTS → LAW → INTERPRETATION → ANALYSIS
   → EVIDENCE → RISK → JUDGMENT → CONCLUSION → ACTION
   (03/04/05 modules are reference material the core
   prompt's mode-inference and commands draw on)
```

## What you still need to do before this is "live"

1. **Populate the real knowledge base.** `knowledge-index.example.json` is a template — it has one placeholder entry and one real-but-illustrative STATIC entry. Every rate/threshold/deadline you actually want the agent to use confidently needs a real, sourced entry (`02-knowledge-layer/update-protocol.md` §5 gives you a minimum-viable single-file starting point).
2. **Wire the retrieval + injection step** in your website backend (`integration/website-integration.md` §1–3).
3. **Run the test suite and red-team checklist** (`06-testing-redteam/`) against your actual deployed system, not just this document set.
4. **Decide your review-queue policy** for `UPDATE KNOWLEDGE` — direct-write vs. human-approved (`update-protocol.md` §2). For anything above STATIC category, human approval before go-live is the safer default.
5. **Add UI-level disclosure and logging** per `integration/website-integration.md` §6 — this is a professional-liability consideration, not just a nice-to-have.

## Maintaining this over time

- Changes to *how the agent reasons* (a new mode, a new command, a tone/format change) → edit `01-core/system-prompt.md`. This should change rarely.
- Changes to *what's currently true* (a new Finance Act rate, a new notification, an amended standard) → go through `02-knowledge-layer/update-protocol.md`, never edited directly into the core prompt.
- Changes to *how a specific domain should be reasoned about* (e.g. a new audit scenario pattern you keep hitting in practice) → add it to the relevant `03-`/`04-`/`05-` module, keeping citations/numbers out of it per the same discipline.
- After any core-prompt or module change: re-run `06-testing-redteam/` before it goes live.

This system is designed to still be correct and maintainable years from now precisely because the parts that will obviously be wrong in a year (rates, deadlines, specific provisions) are never welded into the parts that shouldn't need to change (how to think through an audit, how to structure a tax memo, when to say "verify this").
