Skip to content

Commit 2739779

Browse files
chitcommitclaude
chitcommit
and
claude
authored
docs: optimize canonical .md pack (CHITTY/CHARTER/SECURITY/AGENTS) (#114)
Sync the canonical documentation pack to reflect Phase 3.5/4/6 state and add AGENTS.md for agent registry discoverability. CHITTY.md: - type: summary → architecture (resolves open compliance follow-up) - Fill ChittyID (did:chitty:REG-XE6835) and registration date - Expand endpoint surface from 12 paths to 22 categories matching the 33 route modules in server/routes/ (properties, allocations, classification, COA, valuation, imports, forensics, ChittyID SSO, MCP, etc.) - Dependencies grew from 7 to 13 services, each marked Live / Partial / Pending; flag ChittyChronicle read-side as blocked, ChittyCert + MCP as Phase 5/2 pending CHARTER.md: - Scope updated to reflect shipped capabilities through Phase 6 (allocations, exports, classification trust-path, COA admin, valuation, CSV imports, Schedule E, forensics, inbound email) - API Contract: 12 → ~50 endpoints across 11 categories - Compliance checklist: 8 → 17 items (HMAC webhooks, classification trust path, ChittyID SSO PKCE, multi-currency, schema registration, discovery) - Dependencies marked Live / Partial / Pending - Last Updated: 2026-03-22 → 2026-05-02 SECURITY.md: - Mercury per-tenant HMAC-SHA256 webhook details (7 active registrations) - ChittyID OAuth 2.0 PKCE primary auth path - ChittyOS integrations table (auth direction per peer service) - npm audit alongside pnpm audit (both lock files present) - Bot detection + script injection prevention (PR #95 hardening) - Known Limitations: ChittyChronicle read-side blocked, ChittySchema fall-open, app-level rate limiting open AGENTS.md (new): - Internal AI agents: classification (GPT-4o-mini, L1), advice (GPT-4o), optimizer - MCP capabilities exposed under /api/mcp/* - ChittyOS agents that interact with this service - Dev subagent guidance (chittyschema-overlord, chittycanon-code-cardinal, chittyconnect-concierge, etc.) - Agent trust boundaries (what is and isn't delegated) - Contribution guide for new agent integrations Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent a7d2271 commit 2739779

4 files changed

Lines changed: 316 additions & 77 deletions

File tree

‎AGENTS.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
uri: chittycanon://docs/ops/agents/chittyfinance
3+
namespace: chittycanon://docs/ops
4+
type: agents
5+
version: 1.0.0
6+
status: COMPATIBLE
7+
registered_with: chittycanon://core/services/canon
8+
title: "ChittyFinance Agent Registry"
9+
visibility: PUBLIC
10+
---
11+
12+
# ChittyFinance Agent Registry
13+
14+
Registry of AI agents, ChittyOS subagents, and MCP capabilities relevant to ChittyFinance.
15+
Companion to [CHITTY.md](CHITTY.md), [CHARTER.md](CHARTER.md), [SECURITY.md](SECURITY.md), and [CLAUDE.md](CLAUDE.md).
16+
17+
## Internal AI Agents (run by ChittyFinance)
18+
19+
### Transaction Classification (GPT-4o-mini)
20+
- **Source**: `server/lib/ai-classifier.ts`
21+
- **Trigger**: Mercury webhook ingest (PR #90), CSV import L1 suggest pass
22+
- **Trust level**: L1 — writes `suggested_coa_code` only, never `coa_code`
23+
- **Confidence floor**: 0.80 for bulk-accept eligibility (≤$500, exclude 9010 suspense)
24+
- **Fallbacks**: Keyword matcher → vendor map → suspense (9010); never throws — always returns a suggestion
25+
- **Audit**: Every suggestion writes to `classification_audit` with actor `system:ai-classifier`
26+
27+
### Financial Advice (GPT-4o)
28+
- **Source**: `server/lib/openai.ts`
29+
- **Endpoints**: `/api/ai/advice`, `/api/ai/cost-reduction`, `/api/ai/message`
30+
- **Max tokens**: 500 per request
31+
- **PII policy**: No account numbers or tenant identifiers sent in prompts; only aggregated financial context
32+
- **Fallback**: Rule-based advice when `OPENAI_API_KEY` is unset
33+
34+
### Recurring Charge Optimizer
35+
- **Source**: `server/lib/chargeAutomation.ts`
36+
- **Endpoint**: `/api/charges/optimizations`
37+
- **Recommendations**: cancel / downgrade / consolidate / negotiate
38+
39+
## MCP Capabilities Exposed by ChittyFinance
40+
41+
Mounted under `/api/mcp/*`. Resources include:
42+
- Financial summaries (tenant-scoped)
43+
- Transaction queries
44+
- Property financials (NOI, cap rate, occupancy)
45+
- Allocation rule preview
46+
- Schedule E line summary
47+
48+
Authentication: Bearer service token. See [SECURITY.md](SECURITY.md).
49+
50+
> ⚠️ **Phase 2 remaining**: ChittyConnect MCP integration not yet wired. Internal MCP routes work today; cross-service MCP discovery via ChittyConnect is pending.
51+
52+
## ChittyOS Agents That Interact with ChittyFinance
53+
54+
| Agent | Direction | Purpose |
55+
|-------|-----------|---------|
56+
| `chittyagent-schema` | Inbound (advisory) | Validates `chart_of_accounts`, `classification_audit`, `transactions` schemas; client is fall-open |
57+
| `chittyagent-register` | Outbound (one-time) | Service registered as `did:chitty:REG-XE6835` (2026-02-22) |
58+
| `chittyagent-connect` | Outbound (runtime) | Mercury Bank proxy — every bank API call routes through ChittyConnect |
59+
| `chittyagent-canon` | Inbound (CI) | Audits this repo for canonical pattern adherence |
60+
| `chittyagent-cloudflare` | Outbound (admin) | Hyperdrive, KV, Email Service, WAF rules |
61+
| `chittyagent-notion` | Outbound (state) | Project + Actions DB updates from session lifecycle hooks |
62+
63+
## ChittyOS Subagents Useful for Development
64+
65+
When working in this repo, prefer these subagents (see user's `~/.claude/agents/`):
66+
67+
| Subagent | When to Use |
68+
|----------|-------------|
69+
| `chittyschema-overlord` | Before modifying `database/system.schema.ts` — validates cross-schema impact |
70+
| `chittycanon-code-cardinal` | After writing code touching entity types (P/L/T/E/A) — audits canonical adherence |
71+
| `chittyconnect-concierge` | When adding a new third-party integration or managing credentials |
72+
| `chittyregister-compliance-sergeant` | When updating registration payload or troubleshooting registration failures |
73+
| `chittyagent-neon-schema` | Before deploying — detects drift between Neon DB and service code expectations |
74+
| `chittystorage-sasquatch` | When ingesting documents (CSV imports, bank statements, evidence) |
75+
| `claude-integration-architect` | When designing Claude Skills, MCP servers, or extension integrations |
76+
77+
## Agent Interaction Boundaries
78+
79+
**ChittyFinance never delegates these to external agents:**
80+
- Classification authority (L2 `coa_code` writes) — only authenticated executors with `tenant_users.role` ∈ {owner, admin, manager}
81+
- Reconciled-row mutations — concurrency-locked at the SQL layer
82+
- COA modifications (L4) — only `tenant_users.role` ∈ {owner, admin}
83+
- Webhook signature verification — never bypassed for any agent caller
84+
85+
**ChittyFinance does delegate these to external agents:**
86+
- Identity (ChittyID via OAuth 2.0 PKCE)
87+
- Token validation (ChittyAuth)
88+
- Schema authority (ChittySchema, advisory)
89+
- Audit log canonicality (ChittyChronicle write-side)
90+
- Discovery + heartbeat (ChittyDiscovery)
91+
92+
## Adding a New Agent Integration
93+
94+
1. Read [CHARTER.md](CHARTER.md) — understand scope boundaries (what ChittyFinance IS / IS NOT responsible for)
95+
2. Read upstream service's `CHARTER.md` and `CHITTY.md` — never guess the contract
96+
3. Auth via service token (`Authorization: Bearer ...`) — credentials retrieved at runtime via Cloudflare Secrets, never hardcoded
97+
4. If the agent will write to financial state, document its trust level (L0–L4) and audit trail before merging
98+
5. Update this file and CHARTER.md Dependencies table
99+
100+
## Related Documentation
101+
102+
- [CHITTY.md](CHITTY.md) — Architecture summary + ecosystem position
103+
- [CHARTER.md](CHARTER.md) — API contract + scope + dependencies
104+
- [SECURITY.md](SECURITY.md) — Security model + integration auth patterns
105+
- [CLAUDE.md](CLAUDE.md) — Developer guide + commands

‎CHARTER.md‎

Lines changed: 128 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -25,24 +25,32 @@ ChittyFinance is a **full-stack financial management platform** for the ChittyOS
2525
## Scope
2626

2727
### IS Responsible For
28-
- Financial dashboard with real-time summaries
28+
- Financial dashboard with real-time summaries + consolidated reporting across entities
2929
- Multi-tenant financial data management (IT CAN BE LLC entity structure)
30-
- Mercury Bank integration (via ChittyConnect)
30+
- Mercury Bank integration (direct webhooks + ChittyConnect proxy with static egress IP)
3131
- Wave Accounting integration (OAuth 2.0 + GraphQL)
3232
- Stripe payment processing and webhooks
33-
- AI financial advice (OpenAI GPT-4o)
33+
- AI financial advice (OpenAI GPT-4o) + AI transaction classification (GPT-4o-mini)
34+
- Database-backed Chart of Accounts with L0→L4 trust-path classification (executor/auditor segregation)
3435
- Recurring charge analysis and optimization
35-
- Property management (rent roll, leases)
36-
- Inter-company transaction tracking
36+
- Property management (CRUD, rent roll, leases, P&L, multi-source valuation)
37+
- Lease expiration notifications (cron + dashboard widget + action queue)
38+
- Inter-company transaction tracking + automated allocation engine (management_fee, cost_sharing, rent_passthrough, custom_pct)
39+
- Transaction export (CSV / OFX 1.x / QFX)
40+
- CSV import pipeline (TurboTenant, Mercury, HD Pro, Amazon Business, REI Hub, Wave sync)
41+
- Schedule E tax workspace + line summary
42+
- Forensic accounting (Benford's Law, duplicate detection, flow of funds, damages calculation)
3743
- GitHub integration for project cost attribution
3844
- Tenant-scoped financial data isolation
45+
- Inbound email handling at `finance@chitty.cc` (Cloudflare Email Service)
3946

4047
### IS NOT Responsible For
4148
- Identity generation (ChittyID)
4249
- Token provisioning (ChittyAuth)
4350
- Service registration (ChittyRegister)
4451
- Evidence management (ChittyLedger)
4552
- Legal case management (ChittyCases)
53+
- Property management UI for end-users (ChittyBooks consumes ChittyFinance as engine)
4654

4755
## Dual-Mode Operation
4856

@@ -72,47 +80,125 @@ IT CAN BE LLC (holding)
7280

7381
## Dependencies
7482

75-
| Type | Service | Purpose |
76-
|------|---------|---------|
77-
| Upstream | ChittyAuth | Token validation |
78-
| Upstream | ChittyID | Identity (planned) |
79-
| Peer | ChittyConnect | Mercury Bank proxy |
80-
| Peer | ChittyChronicle | Audit logging (planned) |
81-
| External | Mercury Bank | Banking integration |
82-
| External | Wave Accounting | Accounting integration |
83-
| External | Stripe | Payment processing |
84-
| External | OpenAI | AI financial advice |
85-
| External | GitHub | Project cost attribution |
86-
| Storage | Neon PostgreSQL | Database |
83+
| Type | Service | Status | Purpose |
84+
|------|---------|--------|---------|
85+
| Upstream | ChittyAuth | Live | Token validation |
86+
| Upstream | ChittyID | Live (PR #72) | OAuth 2.0 PKCE SSO |
87+
| Peer | ChittyConnect | Live | Mercury Bank proxy (static egress IP) |
88+
| Peer | ChittyDiscovery | Live (PR #79) | Service self-registration + heartbeat |
89+
| Peer | ChittySchema | Live | Schema registry (advisory client, fall-open) |
90+
| Peer | ChittyChronicle | Partial | Write-side wired (PR #92); read API endpoints (cases/timeline/search) return 404 |
91+
| Peer | ChittyCert | Pending | Certificate issuance (Phase 5) |
92+
| External | Mercury Bank | Live | Banking + 7 per-tenant HMAC webhooks |
93+
| External | Wave Accounting | Live | Accounting integration |
94+
| External | Stripe | Live | Payment processing |
95+
| External | OpenAI | Live | GPT-4o + GPT-4o-mini |
96+
| External | GitHub | Live | Project cost attribution |
97+
| External | Cloudflare Email | Live (PR #102) | Inbound `finance@chitty.cc` |
98+
| Storage | Neon PostgreSQL | Live | Database (`solitary-rice-14149088`) via Hyperdrive `chittyfinance-db` |
99+
| Storage | Cloudflare KV | Live | Sessions, webhook idempotency, OAuth state |
87100

88101
## API Contract
89102

90103
**Base URL**: https://finance.chitty.cc
91104

105+
### Public (no auth)
106+
| Endpoint | Method | Purpose |
107+
|----------|--------|---------|
108+
| `/health` | GET | Health check |
109+
| `/api/v1/status` | GET | Service status |
110+
| `/api/v1/documentation` | GET | OpenAPI spec |
111+
| `/api/session` | GET/POST/DELETE | Session cookie management |
112+
| `/api/auth/chittyid/{authorize,callback}` | GET | ChittyID OAuth 2.0 PKCE |
113+
92114
### Financial Data
93115
| Endpoint | Method | Purpose |
94116
|----------|--------|---------|
95117
| `/api/financial-summary` | GET | Financial summary |
96118
| `/api/transactions` | GET | Transaction list |
97-
| `/api/recurring-charges` | GET | Recurring charges |
98-
| `/api/recurring-charges/:id/optimizations` | GET | AI optimization |
119+
| `/api/transactions/export?format=csv\|ofx\|qfx` | GET | Export (CSV / OFX 1.x / QFX) |
120+
| `/api/charges/recurring` | GET | Recurring charges |
121+
| `/api/charges/optimizations` | GET | AI optimization recommendations |
122+
| `/api/charges/manage` | POST | Cancel / modify recurring charge |
99123

100-
### Integrations
124+
### Tenants & Accounts
101125
| Endpoint | Method | Purpose |
102126
|----------|--------|---------|
103-
| `/api/integrations/status` | GET | Integration config status |
104-
| `/api/integrations/wave/authorize` | GET | Wave OAuth flow |
105-
| `/api/integrations/stripe/connect` | POST | Stripe customer |
106-
| `/api/integrations/stripe/webhook` | POST | Stripe webhooks |
107-
| `/api/mercury/accounts` | GET | Mercury accounts |
127+
| `/api/tenants` | GET | List tenants user has access to |
128+
| `/api/tenants/:id/settings` | GET/PATCH | Tenant settings (bulk-accept opt-out, etc.) |
129+
| `/api/accounts` | GET | List bank accounts (tenant-scoped) |
130+
131+
### Properties (Phase 4)
132+
| Endpoint | Method | Purpose |
133+
|----------|--------|---------|
134+
| `/api/properties` | GET/POST | List/create |
135+
| `/api/properties/:id` | PATCH | Update |
136+
| `/api/properties/:id/units` | POST | Create unit |
137+
| `/api/properties/:id/units/:unitId` | PATCH | Update unit |
138+
| `/api/properties/:id/leases` | POST | Create lease |
139+
| `/api/properties/:id/leases/:leaseId` | PATCH | Update lease |
140+
| `/api/properties/:id/financials` | GET | NOI, cap rate, cash-on-cash, occupancy |
141+
| `/api/properties/:id/rent-roll` | GET | Unit-level rent roll |
142+
| `/api/properties/:id/pnl?start=&end=` | GET | P&L by REI category |
143+
| `/api/properties/:id/valuation` | GET | Aggregated multi-source AVM |
144+
| `/api/properties/:id/valuation/refresh` | POST | Refresh estimates |
145+
| `/api/properties/:id/valuation/history` | GET | Historical timeline |
146+
| `/api/leases/expiring?days=N` | GET | Expiring leases (default 90 days) |
147+
148+
### Allocations (Phase 6)
149+
| Endpoint | Method | Purpose |
150+
|----------|--------|---------|
151+
| `/api/allocations/rules` | GET/POST/PATCH/DELETE | CRUD allocation rules |
152+
| `/api/allocations/preview` | POST | Preview allocation |
153+
| `/api/allocations/execute` | POST | Execute allocation |
154+
| `/api/allocations/runs` | GET | List runs |
155+
156+
### Classification & COA (Phase 3.5)
157+
| Endpoint | Method | Purpose |
158+
|----------|--------|---------|
159+
| `/api/classification/queue` | GET | Pending classification queue |
160+
| `/api/classification/suggest` | POST | AI-suggest COA code (L1) |
161+
| `/api/classification/classify` | POST | Set authoritative COA (L2) |
162+
| `/api/classification/bulk-accept` | POST | Bulk-accept high-confidence (≥0.80, ≤$500) |
163+
| `/api/chart-of-accounts` | GET/POST/PATCH | COA admin (L4 owner/admin only) |
164+
165+
### Tax & Reports
166+
| Endpoint | Method | Purpose |
167+
|----------|--------|---------|
168+
| `/api/tax/schedule-e` | GET | Schedule E export |
169+
| `/api/tax/line-summary` | GET | Tax line summary |
170+
| `/api/reports/consolidated` | GET | Consolidated reporting across entities |
171+
| `/api/portfolio` | GET | Portfolio summary |
172+
173+
### Imports (Phase 4)
174+
| Endpoint | Method | Purpose |
175+
|----------|--------|---------|
176+
| `/api/import/turbotenant` | POST | TurboTenant CSV (deposits + rent roll) |
177+
| `/api/import/mercury` | POST | Mercury CSV (auto-resolve account) |
178+
| `/api/import/hd-pro` | POST | HD Pro CSV (3K items, 24 job normalizations) |
179+
| `/api/import/amazon` | POST | Amazon Business (returns dedup, payment cards) |
180+
| `/api/import/rei-hub` | POST | REI Hub general ledger |
181+
| `/api/import/wave-sync` | POST | Wave OAuth sync |
108182

109183
### AI Services
110184
| Endpoint | Method | Purpose |
111185
|----------|--------|---------|
112-
| `/api/ai/advice` | POST | Financial advice |
186+
| `/api/ai/advice` | POST | GPT-4o financial advice |
113187
| `/api/ai/cost-reduction` | POST | Cost reduction plan |
114188
| `/api/ai/message` | POST | Conversational AI |
115189

190+
### Integrations & Webhooks
191+
| Endpoint | Method | Purpose |
192+
|----------|--------|---------|
193+
| `/api/integrations/status` | GET | Integration config status |
194+
| `/api/integrations/wave/{authorize,callback,refresh}` | GET/POST | Wave OAuth flow |
195+
| `/api/integrations/stripe/{connect,checkout,webhook}` | POST | Stripe customer + checkout + webhook |
196+
| `/api/mercury/{accounts,select-accounts}` | GET/POST | Mercury accounts via ChittyConnect |
197+
| `/api/integrations/{mercury,wave}/webhook` | POST | Webhooks (per-tenant HMAC-SHA256) |
198+
199+
### Forensics (Phase 4)
200+
21 endpoints under `/api/forensics/*` — investigations, evidence, chain-of-custody, Benford's Law, duplicate detection, flow of funds, damages calculation, reports.
201+
116202
## Ownership
117203

118204
| Role | Owner |
@@ -148,14 +234,23 @@ This charter is part of a synchronized documentation triad. Changes to shared fi
148234

149235
## Compliance
150236

151-
- [x] Service registered in ChittyRegistry (did:chitty:REG-XE6835, 2026-02-22)
152-
- [x] Health endpoint operational at /health
237+
- [x] Service registered in ChittyRegistry (`did:chitty:REG-XE6835`, 2026-02-22)
238+
- [x] Health endpoint operational at `/health`
153239
- [x] CLAUDE.md development guide present
154240
- [x] CHARTER.md present
155-
- [x] CHITTY.md present
156-
- [x] OAuth security (CSRF-protected state tokens)
157-
- [x] Webhook signature verification (Stripe)
158-
- [x] Multi-tenant data isolation
241+
- [x] CHITTY.md present (`type: architecture`)
242+
- [x] SECURITY.md present
243+
- [x] AGENTS.md present
244+
- [x] OAuth security: CSRF-protected HMAC-SHA256 state tokens (10-min expiry)
245+
- [x] Webhook signature verification: Stripe + Mercury (per-tenant HMAC)
246+
- [x] Multi-tenant data isolation enforced at storage abstraction layer
247+
- [x] Classification trust-path: L0→L4 with executor/auditor segregation
248+
- [x] Concurrency-safe reconciled lock (no TOCTOU)
249+
- [x] Ledger audit coverage: all financial mutations write to ChittyChronicle
250+
- [x] ChittyID SSO (OAuth 2.0 PKCE, PR #72)
251+
- [x] Multi-currency (ISO 4217)
252+
- [x] Schema registered with ChittySchema (chittyschema#11)
253+
- [x] Self-registration with ChittyDiscovery (PR #79)
159254

160255
---
161-
*Charter Version: 2.0.0 | Last Updated: 2026-03-22*
256+
*Charter Version: 2.0.0 | Last Updated: 2026-05-02*

0 commit comments

Comments
 (0)