InfraNotes Accounting Engine · v0
Welcome
Select a document from the sidebar to read it.
InfraNotes Accounting — Smart Engine
Standalone Rust gRPC service that powers all deterministic, rule-based accounting automation within the InfraNotes Accounting System.
The Smart Engine answers questions like "What GL account does this transaction map to?" and "Does this bank statement match this journal entry?" — using configurable rules, not black-box models.
It is not a compliance engine. Regulatory compliance lives in UCE (Universal Compliance Engine). The Smart Engine owns accounting business logic exclusively.
Why This Exists
Accounting automation typically falls into two camps: manual mappings maintained in spreadsheets, or opaque ML models that can't explain their decisions to auditors. The Smart Engine takes a third path — deterministic rule evaluation with full audit trails. Every decision is reproducible months later by replaying the same input against the same rule version.
Design Principles
| Principle | What It Means |
|---|---|
| No AI/ML | Rule trees, configurable thresholds, statistical functions (z-scores, moving averages), and pattern matching. No neural networks, no probabilistic inference. Given the same input and rule version, you get the same output. Always. |
| Fail-Closed | If no classification rule matches, the transaction is flagged for manual review. It is never silently assigned to a default account. |
| Stateless | Rules are loaded on startup or hot-reloaded on version change. Evaluation is pure: rules + input = output. No in-process state between requests. |
| Auditable | Every evaluation returns the matched rule ID, rule version, and a full evaluation trace showing which rules were tested and why they passed or failed. |
| Bounded Execution | CEL expressions run in a sandbox with configurable memory limits and evaluation timeouts. No unbounded recursion, no runaway evaluations. |
Capabilities
Transaction Classification
Maps incoming financial transactions to the correct GL account, cost center, department, and custom dimensions. Rules are evaluated in priority order — first match wins. If nothing matches, the transaction is flagged for human review with a full trace of every rule that was evaluated.
Supports both single-transaction classification and batch processing (optimized for bank statement imports of hundreds to thousands of transactions).
Reconciliation Matching
Deterministic matching engine for bank reconciliation and intercompany reconciliation. Supports exact reference matching, reference+date matching, amount+date matching, and 1-to-many / many-to-1 matching for split transactions.
Confidence scoring is discrete (criteria satisfied out of total possible), not probabilistic. Unmatched items include near-miss details: the closest potential match and why it failed.
Tolerances are configurable per matching run: date tolerance (days), amount tolerance (absolute), and FX tolerance (percentage for multi-currency).
Anomaly & Fraud Detection
Runs on every journal entry after posting. Five rule types:
- Threshold — single transaction exceeds a configurable amount per account, vendor, or entry type
- Statistical Outlier — z-score exceeds configurable sigma against historical averages (stats provided by calling service)
- Duplicate Detection — same amount + same vendor + same date within tolerance
- Velocity — vendor period total exceeds a percentage of the trailing N-period average
- Pattern — round-number amounts, just-below-approval-threshold amounts, weekend/holiday postings, off-hours postings
Severity levels control behavior: info (logged only), warning (flagged for review, entry posted), critical (entry blocked in draft, reviewer notified). False-positive dismissals are recorded for periodic rule tuning but never auto-adjust rules.
Close Readiness Evaluation
Evaluates whether an entity is ready to close a fiscal period. Checks:
- Completeness — all required close tasks are done (configurable per entity)
- Dependencies — downstream tasks cannot be complete if upstream dependencies are incomplete
- Threshold Gates — max unmatched bank transactions, max unresolved critical anomalies, max intercompany imbalance
- Sub-Ledger Agreement — AR/AP sub-ledger totals must equal their control account balances
Returns a readiness score (0–100), a pass/fail per check, and a list of blocking items with resolution actions.
Architecture
┌─────────────────────────────────────────────────────────┐
│ Cargo Workspace │
│ │
│ ┌─────────────────┐ ┌──────────────┐ ┌───────────┐ │
│ │ smart-engine-grpc│ │smart-engine- │ │smart- │ │
│ │ │ │ core │ │engine-cli │ │
│ │ tonic gRPC server│ │ │ │ │ │
│ │ OpenTelemetry │──│ Classification│──│ Rule test │ │
│ │ Prometheus │ │ Matching │ │ Validation│ │
│ │ Health checks │ │ Anomaly │ │ Dry-run │ │
│ │ Rule loading │ │ Close Ready │ │ Signing │ │
│ │ Audit logging │ │ │ │ │ │
│ └────────┬─────────┘ └──────────────┘ └───────────┘ │
│ │ │
└───────────┼──────────────────────────────────────────────┘
│
▼
┌──────────────┐
│ PostgreSQL 18 │
│ │
│ Rule storage │
│ Rule sets │
│ Audit log │
└──────────────┘
- smart-engine-core — Pure rule evaluation library. Contains the classification engine, matching engine, anomaly detector, and close readiness evaluator. No I/O, no database, no network. All logic lives here.
- smart-engine-grpc — gRPC service wrapping core. Handles request/response serialization, observability (OpenTelemetry traces, Prometheus metrics), health checks, and rule loading from PostgreSQL.
- smart-engine-cli — CLI tool for accountants and engineers. Test rules against sample transactions, validate syntax and types, dry-run before deploying to production.
Rule System
Rules are defined in YAML with JSON Schema validation. Conditions use CEL (Common Expression Language) — deterministic, type-safe, sandboxed expressions with no side effects or I/O.
Custom CEL functions extend the standard library for financial logic: contains_keyword, matches_pattern, amount_in_range, day_of_week, is_weekend, is_round_number, z_score, percent_change.
Action payload validation treats any JSON key named expression (case-insensitive) or ending with _expression as CEL and compiles it during rule validation. When storing plain strings in actions, avoid those key names (for example use description_template instead of description_expression) unless the value is intended to be a CEL expression.
Rules are versioned with semver. Updates create new versions (old versions are preserved). The engine evaluates against the active version and can replay historical evaluations against any past version. Every rule is signed (SHA-256 hash of the YAML content, signed with the service key) for tamper evidence.
gRPC API
| RPC | Called By | Purpose |
|---|---|---|
ClassifyTransaction |
Core Ledger | Classify a single transaction |
ClassifyBatch |
Core Ledger | Classify a batch of transactions (bank imports) |
MatchReconciliation |
Reconciliation & Close | Match bank or intercompany items |
DetectAnomalies |
Core Ledger | Run anomaly detection on a journal entry |
RecordAnomalyDismissal |
Any service | Record dismissal of a detected anomaly |
EvaluateCloseReadiness |
Reconciliation & Close | Check if a period is ready to close |
GetRuleVersion |
Any service | Cache invalidation check |
ValidateRules |
CLI, Admin API | Pre-deployment rule validation |
Observability
| Signal | Implementation |
|---|---|
| Traces | OpenTelemetry spans per RPC. Includes rule evaluation count, matched rule ID, evaluation duration. Trace IDs propagated from calling Go services. |
| Metrics | Prometheus: smart_engine_evaluations_total, smart_engine_evaluation_duration_seconds, smart_engine_rules_loaded, smart_engine_anomalies_detected_total |
| Logs | Structured JSON via tracing crate. Classification failures, critical anomalies, and close readiness evaluations are always logged. |
| Health | gRPC health check reporting rule load status, database connectivity, and memory usage. |
Performance Targets
| Operation | p95 Latency |
|---|---|
| Single transaction classification | < 50ms |
| Batch classification (1,000 txns) | < 200ms |
| Reconciliation matching (1,000 pairs) | < 200ms |
| Anomaly detection (per journal entry) | < 20ms |
| Close readiness evaluation | < 100ms |
| Rule hot-reload | < 5 seconds |
Tech Stack
| Component | Technology |
|---|---|
| Language | Rust (2024 edition) |
| Interface | gRPC via tonic |
| Database | PostgreSQL 18 |
| Rule Conditions | CEL (Common Expression Language) |
| Rule Format | YAML with JSON Schema validation |
| Tracing | OpenTelemetry |
| Metrics | Prometheus |
| Logging | tracing (structured JSON) |
| Container | Multi-stage build, distroless runtime |
| Orchestration | Kubernetes, Helm chart with HPA |
Deployment
Stateless and horizontally scalable. Each instance loads rules from PostgreSQL independently and hot-reloads on version changes. Deployed as a static musl binary in a distroless container. Recommended baseline: 2 vCPU, 512 MB RAM per instance, scaled via HPA on CPU utilization.
Project Documents
| Document | Description |
|---|---|
| PRD.md | Product Requirements Document — full specification |
| execution_plan.md | Phased implementation plan with progress tracking |