English · Persian / فارسی

Azarakhsh

Electrical engineering calculator — Flutter UI, Rust core (FRB v2), Metis AI, IEC/IEEE standards.

Quick start · Architecture · Gates · Docs · Production readiness

---

Table of Contents

Jump to section

• What is Azarakhsh?
• What it is NOT
• Architecture
• AI pipeline (Metis)
• Quick start
• Repository layout
• Acceptance gates
• Manual gates (device)
• CI & quality
• Documentation
• Contributing
• Security
• License

---

What is Azarakhsh?

Azarakhsh is a field-ready electrical engineering calculator for harmonics (IEEE 519-2022), cable ampacity (IEC 60364), short-circuit factors (IEC 60909), motor nameplate OCR, and standards-grounded RAG — with a Rust compute core behind Flutter and optional offline ONNX when Metis is unavailable.

Field	Detail
Version	1.0.0+1 (Post-MVP Golden)
UI	Flutter 3 · Riverpod 3 · go_router · FA/EN l10n (EN default in this file)
Core	azarakhsh_native Rust via flutter_rust_bridge 2.13
AI	Metis API — user-brought key (ADR-0013)
RAG	sqlite-vec + RRF hybrid (ADR-0010)
Proof	python bench/suite/run_suite.py --summary — 22 gates

Structure

• azarakhsh_app/ — Flutter UI (Riverpod 3, go_router)
• packages/azarakhsh_native/ — Rust engine via flutter_rust_bridge
• packages/azarakhsh_zig/ — Zig ArenaAllocator C ABI glue

Governance

• Architecture.toml — layer invariants (scripts/arch-check.ps1)
• docs/adr/ — architecture decision records (0001–0014)
• docs/contracts/ — phase contract gates (phase00–phase07)

---

What it is NOT

Misread	Reality
❌ Cloud-only without privacy	✅ User-brought Metis key; no master key in APK
❌ Generic chatbot	✅ Citation-verified RAG over IEC/IEEE corpus
❌ Emulator perf certification	✅ p90 ≤ 8.33 ms gate is physical 120 Hz device only
❌ Full ONNX in default build	✅ ai_offline_tier feature — optional YOLOv8 + PP-OCR

---

Architecture

flowchart TB
  subgraph flutter [Flutter azarakhsh_app]
    UI[UI Pages]
    EP[EngineService]
    L10N[l10n EN default / FA]
  end
  subgraph frb [flutter_rust_bridge]
    API[api/metis.rs harmonics.rs]
  end
  subgraph rust [Rust core]
    MATH[core math PID FFT]
    STD[standards TOML loader]
    AI[MetisClient RAG citation]
    ONNX[onnx offline tier]
  end
  UI --> EP --> API --> MATH
  API --> STD
  API --> AI
  API --> ONNX

Loading

---

AI pipeline (Metis)

flowchart LR
  A0[MetisClient] --> A1[Motor 3-tier extract]
  A0 --> A2[sqlite-vec RRF]
  A2 --> A3[CHAT + citation verify]
  A0 --> Aoff[ONNX offline optional]

Loading

Tier	Motor scan	Model
1	/v1/extract	gpt-4o-mini (404 → skip to tier 2)
2	Multimodal chat	gpt-4o-mini + image_url
3	Rule OCR	Local fallback
RAG embed	/v1/embeddings	text-embedding-3-small
Synthesis	/v1/chat/completions	gpt-4.1-nano

Probe: python scripts/probe_metis_models.py — see METIS_MODELS.

---

Quick start

cd azarakhsh_app
flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter run -d windows

Metis key: in-app Settings → Metis or .env for scripts (gitignored). See INSTALL.md.

---

Repository layout

Azarakhsh/
├── azarakhsh_app/
├── packages/azarakhsh_native/
├── packages/azarakhsh_zig/
├── docs/adr/ docs/contracts/ docs/standards/
├── bench/suite/
├── scripts/
└── assets/logo.png

---

Acceptance gates

python bench/suite/run_suite.py --summary

Suite	Count	Examples
Cargo	19	standards_golden_suite, rag_rrf_beats_keyword_only
Flutter	3	l10n_smoke_test, metis_key_disclosure_ui_gate
Total	22	DoD ≥ 18

---

Manual gates (device)

Gate	Command
Perf p90 @ 120 Hz	.\scripts\perf_strict_device.ps1
Android 16 KB	./scripts/verify_android_16kb.sh after release APK
Metis live probe	python scripts/probe_metis_models.py
ONNX offline	cargo test --features ai_offline_tier

---

CI & quality

flowchart LR
  push[push/PR] --> ci[ci.yml]
  ci --> suite[run_suite 22 gates]
  ci --> apk[APK release + 16KB verify]
  push --> sc[supply-chain.yml]
  cron[weekly] --> staging[metis-staging.yml]

Loading

Workflows: ci.yml · supply-chain.yml · release.yml

---

Documentation

Document	Contents
README.fa.md	Persian companion
docs/README.md	Docs hub (EN)
CONTRIBUTING.md	Contributing
SECURITY.md	Security policy
docs/LOGO.md	Logo prompt & assets
docs/OFFLINE_TIER.md	ONNX offline feature

---

Contributing

See CONTRIBUTING.md (فارسی). Run scripts/rebuild.ps1 before PRs.

---

Security

User-brought Metis keys only. See SECURITY.md.

---

License

See repository license. Standards cite docs/standards/SOURCES.md.

---

Azarakhsh — verified gates, honest device checks, standards-grounded AI.

Languages: English · فارسی