Skip to content

Changelog

All notable changes to Feoda's documentation are logged here.

The format follows Keep a Changelog.

[2026-04-28] — AI Platform Target Architecture (Revision)

Changed

  • tech/architecture/ai-platform/target-architecture.md — Revised after re-reading the Corporate AI Strategy. Applied the principle that the strategy fixes goals and governance, not vendors. Vendor swaps: Portkey → Cloudflare AI Gateway + in-house Policy Worker (§4); Pinecone Assistant → Cloudflare Vectorize + D1 FTS5 + Cohere/Voyage reranker via gateway (§5.1, §5.7); Nango → native connectors first with Nango retained as fallback (§6.1). Architecture additions: agentic answering pattern with a tool catalog as the default (§5.6), replacing one-shot retrieval; Vectorize per-tenant namespaces for hard isolation (§5.3); optional Anthropic Contextual Retrieval enrichment routed through OpenRouter for cost (§6.3); Cloudflare Access (Entra-backed) for T1 identity in V1. Policy Worker contract added (§4.5). All governance commitments preserved unchanged: hard provider/model allowlist, per-principal rate limits + spend caps, PII redaction in transit (broader regex set than any third-party gateway), surrogate-identity audit logs, retrieval-time ACL, no live PII in prompts, source-of-truth-stays-put. Indicative monthly cost falls from ~$185–270 to ~$80–140. AP-03 evaluation required for Cloudflare, OpenRouter, and Cohere/Voyage before production. Frontmatter status changed to draft (revised); full revision rationale recorded in §14 Status log. Status: Draft (revised).

[2026-04-24] — Sprint 2 Retrospective

Added

  • solutions/arm/standalone/sprints/sprint-retrospectives/sprint-2.md — Sprint 2 retrospective for the ARM Standalone (Feoda BI) project. Captures per-person feedback (Ola, Samawal, Monther, Areej, Sarah), consolidates the issues raised (rebase/merge & migration conflicts, AI context loss, AI hallucinations, AI budget limits, story clarity for QA, PR convention adherence), and records team decisions (build pipeline fixes + migration hidden-conflict check + branch-protection re-attach, pre-PR conflict check, Opus-for-planning / Sonnet-for-execution interim AI split, story template update separating business impact from technical detail, QA pairing with devs during refinement). Closes carryovers #38 PDF Invoice and notes #80 Tenant Management ~2 SP rollover into Sprint 3. Status: Approved.

Changed

  • mkdocs/mkdocs.yml — Added "Sprint Retrospectives" sub-nav under ARM Standalone Sprints with the Sprint 2 entry.
  • solutions/arm/standalone/sprints/sprint-retrospectives/README.md — Added index table linking to Sprint 2 retrospective.

[2026-04-23] — AI Platform Target Architecture

Added

  • tech/architecture/ai-platform/target-architecture.md — Target-state design of the corporate Feoda AI Platform. Defines: three-tier identity model (Entra for Feoda staff, Clerk for client staff and end-users); Portkey + OpenRouter gateway with hard provider allowlist; Pinecone Assistant as unified RAG layer with metadata-based ACL by client_tag / audience / tier_required; Nango as the source-connector platform; Cloudflare Workers + R2 + D1 as platform runtime; Axiom as managed audit log store with 90-day hot / 1-year warm / 7-year cold tiered retention; surrogate-identity logging pattern; PII policy (no live PII in prompts); cross-border posture across UAE PDPL, KSA PDPL, and Australian APPs; vendor and cost summary; vertical-slice delivery plan V1 (docs assistant on the new stack), V2 (developer code review), V3 (SDR), V4 (support triage), V5+ (channel expansion); open questions; status log. Status: Draft.

Changed

  • mkdocs/mkdocs.yml — AI Platform sub-nav extended with Target Architecture entry.
  • tech/architecture/ai-platform/README.md — Contents table updated; status log appended.

[2026-04-22] — AI Platform Architecture

Added

  • tech/architecture/ai-platform/ — New folder for the Feoda AI Platform architecture (corporate-wide, parent of the documentation assistant and all future AI subsystems).
  • tech/architecture/ai-platform/README.md — Landing page: scope, contents index, relationship to AI Strategy and action plans.
  • tech/architecture/ai-platform/current-state.md — As-built Phase 2 documentation assistant: Vercel serverless api/chat.js + Groq retrieval + Claude answering + chat widget; data and trust boundaries; configuration; limits and cost; observability gaps that feed AP-05; open questions. Status: Draft.
  • tech/architecture/ai-platform/subsystems/ — Reserved folder for per-subsystem designs (documentation assistant target, NetSuite/ARM Q&A, sales/support AI, client-facing channels). To be populated after target architecture is authored.

Changed

  • mkdocs/mkdocs.yml — Architecture section restructured: AI Platform is now a sub-section with Overview and Current State entries.

[2026-04-22] — AI Strategy Execution Scaffolding

Added

  • company/strategy/baselines.md — KPI measurement methodology and Q1 baselines for all KPIs in AI Strategy Section 11. Includes definition, data source, owner, cadence, and baseline value (or pending capture date) per KPI; baseline-capture plan with owners and target dates; reading log for quarterly updates.
  • company/strategy/action-plans/ — New folder for time-bound execution plans that operationalise the AI Strategy.
  • company/strategy/action-plans/README.md — Folder overview, action-plan index, authoring rules, and status definitions.
  • company/strategy/action-plans/ap-01-identity-bound-ai-access.md — AP-01 covering Objective 1 (universal identity-bound AI access by month 6).
  • company/strategy/action-plans/ap-02-foundational-ai-literacy-training.md — AP-02 covering Objective 7 foundational training (mandatory, gates expanded access, by month 6).
  • company/strategy/action-plans/ap-03-approved-provider-list.md — AP-03 covering ratification and publication of the Approved Provider List (by month 2).
  • company/strategy/action-plans/ap-04-documentation-governance-workflow.md — AP-04 covering Objective 3 (AI-audited documentation governance, by month 9).
  • company/strategy/action-plans/ap-05-audit-logging-infrastructure.md — AP-05 covering Phase 1 audit-logging deliverable (by month 6).
  • company/strategy/approved-providers.md — Skeleton document for the Approved Provider List with eligibility tiers, candidate provider table, prohibited tools, and add/remove process. Status: Draft — pending evidence collection under AP-03.

Changed

  • company/strategy/README.md — Added approved-providers.md, baselines.md, and action-plans/ to the contents table.
  • mkdocs/mkdocs.yml — Added Approved Providers, KPI Baselines, and Action Plans (with all five APs) to Company → Strategy nav.

[2026-04-21] — Corporate AI Strategy v1.0

Added

  • company/strategy/ — New top-level folder for corporate strategy documents.
  • company/strategy/README.md — Folder overview, scope, and authoring rules.
  • company/strategy/ai-strategy.md — Corporate AI Strategy v1.0: 18-month strategy governing how Feoda adopts and applies AI in its internal operations across all departments (Tech, Delivery, Sales & Marketing, Support, Finance, HR, Legal) and offices (Singapore HQ, UAE, Australia, India). Defines vision, 8 guiding principles, scope (internal AI vs product AI), 6 strategic objectives, AI maturity model, governance model with risk-tier approval thresholds, comprehensive guardrails (data classification, approved/prohibited providers, human-in-the-loop, audit, regional compliance, education sector sensitivity), departmental application, investment framework, KPIs, 4-phase roadmap, RACI, and review cadence. Living document, owned by Head of Technology, reviewed quarterly.

Changed

  • mkdocs/mkdocs.yml — Added Strategy section under Company nav.
  • company/about-feoda.md — Headquarters corrected to Australia (Melbourne); UAE listed as office. Note added that HQ is planned to relocate to Singapore.

Flagged for Follow-Up

  • Planned HQ relocation to Singapore — Both company/about-feoda.md and company/strategy/ai-strategy.md (Section 8.6) to be updated once the Singapore HQ move is effective. Strategy requires a Singapore regional addendum before AI workflows are deployed under the new HQ.

[2026-04-20] — Compliance Audit & Fixes

Fixed

  • Broken links — templates/ → doc-templates/ rename propagation: Updated 8 broken links across README.md, meetings/README.md, company/processes/README.md, company/policies/README.md, tech/decisions/README.md, tech/runbooks/README.md. Also updated 5 references in PROJECT_INSTRUCTIONS.md itself.
  • Broken links — wrong relative path depth: Fixed 14 links in solutions/arm/processes/billing-process.md, payment-method-change.md, rps-payment-processing.md (used ../../ instead of ../../../). Fixed 1 link in solutions/arm/standalone/decisions/technology-stack-comparison.md. Fixed 2 links in solutions/arm/standalone/technical/implementation-kickoff.md.
  • Broken links — client docs: Fixed 2 links in clients/pymble/design/integrations.md (wrong path depth to solutions/).
  • Missing frontmatter: Added full YAML frontmatter to solutions/arm/standalone/design/opening-balance-scenarios.md and solutions/arm/standalone/requirements/brs-gap-analysis.md.
  • Incomplete frontmatter: Completed solutions/arm/standalone/sprints/sprint-plan.md (had only title, now has all 10 required fields). Added missing related-documents field to 8 Pymble client files.
  • Duplicate file: Removed solutions/arm/standalone/decisions/implementation-kickoff.md (byte-for-byte identical to solutions/arm/standalone/technical/implementation-kickoff.md).
  • Misplaced files: Moved Feoda BI BRS Gap Analysis V1.xlsx from repo root to solutions/arm/standalone/requirements/feoda-bi-brs-gap-analysis-v1.xlsx (kebab-case). Deleted backup copy.
  • Missing README.md files: Created README.md in 8 directories that were missing them (clients/_template/, meeting frames/ dirs, asset subdirs).

Updated

  • CHANGELOG.md — Backfilled all missing entries from 2026-02-23 through 2026-04-17 (~55 commits, ~2 months of unlogged work).

[2026-04-17] — Sprint Planning: Sprint 3 & Restructure (backfilled)

Added

  • solutions/arm/standalone/sprints/sprint-plans/sprint-3.md — Sprint 3 plan stub.

Changed

  • Restructured solutions/arm/standalone/sprints/ folder — split individual sprint plans into sprint-plans/ subfolder, added sprint-retrospectives/ subfolder.
  • Updated sprint plan: re-estimated #55 (Parent Portal) from 3 → 8 SP and #34 (Billing Cycle Close) from 3 → 5 SP.

[2026-04-15] — BRS Gap Analysis (backfilled)

Added

  • solutions/arm/standalone/requirements/brs-gap-analysis.md — Critical review of BRS Gap Analysis spreadsheet against design documents and Azure DevOps stories.

[2026-04-03] — Sprint Plan & Tracking (backfilled)

Added

  • solutions/arm/standalone/sprints/sprint-plan.md — Sprint plan page with Mermaid charts, progress tracking, and Azure DevOps sync.
  • assets/css/sprint-plan.css — Sprint plan styling.

Updated

  • Sprint plan synced with Azure DevOps Sprint 2 status (2 updates).

[2026-03-12] — Opening Balance Scenarios (backfilled)

Added

  • solutions/arm/standalone/design/opening-balance-scenarios.md — BI-37: All business scenarios for opening balance, credit balance, and carry-forward handling.
  • P5/P6 overpayment reallocation scenarios added.

Changed

  • Credit balance moved from billing_profile to debtor level in data model.

[2026-03-12] — Development Conventions (backfilled)

Added

  • tech/development/conventions/branch-conventions.md — Git branch naming and workflow rules.
  • tech/development/conventions/code-conventions.md — Code style, database naming, and standards.
  • tech/development/conventions/developer-onboarding.md — New developer setup guide.
  • tech/development/conventions/cross-repo-pattern.md — How docs are shared across repositories via git submodule.
  • tech/development/contribution-guide.md — Contribution guide for developers.

[2026-03-05] — ARM Standalone: Implementation Kickoff & Cost Projections (backfilled)

Added

  • solutions/arm/standalone/technical/implementation-kickoff.md — Sprint 0 implementation kickoff guide (development environment, project structure, first tasks).
  • solutions/arm/standalone/decisions/technology-stack-comparison.md — Full technology stack evaluation (Node.js, PostgreSQL, React, Azure vs alternatives).
  • solutions/arm/standalone/decisions/cost-projections.md — Infrastructure cost estimates at each growth phase.

Updated

  • ARM standalone data model iterated (multiple fixes).
  • ARM standalone overview updated.

[2026-03-03] — ARM Standalone: Requirements & Design (backfilled)

Added

  • solutions/arm/standalone/requirements/business-requirements.md — Business Requirements Specification (BRS).
  • solutions/arm/standalone/requirements/system-requirements.md — System Requirements Specification (SRS).
  • solutions/arm/standalone/design/data-model.md — Data model design.
  • solutions/arm/standalone/design/process-flows.md — Process flow diagrams.
  • solutions/arm/standalone/design/configurator-specification.md — Billing configurator specification.
  • solutions/arm/standalone/design/integration-specification.md — Integration specification.
  • ARM standalone overview and navigation structure (8 documents total).

[2026-03-02] — Configurator Discussion Meeting (backfilled)

Added

  • meetings/2026-02-19-configurator-discussion/extraction.md — Structured knowledge extraction from the configurator architecture discussion.
  • meetings/2026-02-19-configurator-discussion/transcript.txt — Meeting transcript.
  • meetings/2026-02-19-configurator-discussion/frames/ — Extracted video frames.
  • Meeting screenshots moved to assets/images/meetings/2026-02-19-configurator-discussion/.

[2026-02-26] — AI Chat Assistant: Phase 2 (backfilled)

Added

  • api/chat.js — Vercel serverless function: Groq (Llama 3.3 70B) for retrieval, Claude Sonnet for answering. Includes conversation history, synonym expansion, annotated file tree.
  • assets/js/chat-widget.js — Chat widget frontend embedded in MkDocs site. Features: expandable sources with clickable links, session persistence across page navigations, collapsed by default.
  • assets/css/chat-widget.css — Chat widget styling.

Fixed (iterative, 14 commits)

  • Pinned mkdocs==1.6.1 and mkdocs-material==9.7.2 to prevent breaking upgrades.
  • Fixed exclude_docs blocking Material theme CSS/JS output.
  • Improved AI: conversation history, synonym expansion, annotated file tree, meetings included.
  • Fixed SyntaxError from duplicate code in chat-widget.js.
  • Fixed .md file bundling into Vercel serverless function.
  • Fixed Anthropic API payload (messages field outside JSON body).
  • Excluded api/ from MkDocs output so Vercel runs it as serverless function.
  • Increased maxDuration to 60s, added AbortController timeouts, switched to faster Groq model.
  • Sources: only show files Claude actually used; expandable with clickable links.
  • Chat persistence via sessionStorage across page navigations.
  • Chat panel collapse via CSS display, collapsed by default.
  • Used HTML comment marker for sources instead of JSON.

[2026-02-26] — Roadmap & Copilot Instructions (backfilled)

Added

  • ROADMAP.md — Platform roadmap: Phase 1 (Docs Site), Phase 2 (AI Assistant), Phase 3 (Unified Auth), Phase 4 (Client-Facing Chat).
  • .github/copilot-instructions.md — Copilot instructions for AI assistants working in this repo.

[2026-02-25] — Infrastructure & Deployment (backfilled)

Added

  • mkdocs/mkdocs.yml — MkDocs site configuration (moved into repo at mkdocs/).
  • start-site.sh — Local development convenience script.
  • vercel.json — Vercel deployment configuration.
  • middleware.js — Basic Auth site protection (temporary, username: FeodaAdmin).
  • package.json — Added with type:module for ESM support.
  • GitHub Actions workflow for gh-pages deployment (later disabled in favor of Vercel).

Fixed (iterative, 5 commits)

  • Used --break-system-packages for Vercel Python environment.
  • Fixed python -m mkdocs PATH issue.
  • Removed next/server dependency from middleware.
  • Disabled gh-pages trigger after switching to Vercel.

[2026-02-23] - Client Folder Creation (Saint Edwards, Al Faisal, Pymble)

Added

  • clients/saint-edwards/ — Full implementation folder (12 files). Meaningful content in: overview.md (~920 students, 1 campus, yearly billing, OTP auth, payment terms 20 days in 2026), design/solution-design.md (automated configurator, flexible payment dates), design/integrations.md (SIS, eway, ABA), support/known-issues.md (KI-001: billing instruction regeneration after student count changes).
  • clients/al-faisal/ — Full implementation folder (12 files). Meaningful content in: overview.md (multiple campuses, CSV billing instructions, 4-term billing), design/solution-design.md (CSV import, manual campus reconciliation, enrollment deposits via enrollment module), design/integrations.md (Central SIS on hold — data quality issues, eway, ABA), support/known-issues.md (KI-001: Central SIS API data quality — deactivated, manual CSV workaround).
  • clients/pymble/ — Full implementation folder (13 files). Meaningful content in: overview.md (most feature-rich ARM implementation, My Pymble portal integration), design/solution-design.md (billing orders, review suitelet, term/annual choice, building levy, 2.5% annual discount, annual payment date splitting, SSO/JWT auth), design/integrations.md (data warehouse Excel source, My Pymble portal + JWT SSO, eway, ABA, Edstart, B Pay), customizations/scripts.md (review suitelet, payment suitelet, JWT URL generator), support/known-issues.md (KI-001: invoice visibility in portal in progress; KI-002: billing orders accidentally closed workaround).

Updated

  • clients/README.md — Client Index updated with all three active clients.

[2026-02-18] - ARM Process Documentation (Meeting Extraction)

Added

  • meetings/2026-02-17-feoda-process-updates/extraction.md — Full meeting extraction from the Feoda Process & Updates Session (2026-02-17). Covers the 4×4 Framework, three client walkthroughs, RPS payment processing, and payment method changes.
  • solutions/arm/processes/billing-process.md — End-to-end ARM billing process documentation using the 4×4 Framework (4 NetSuite records × 4 Feoda processes), with client implementation comparison table.
  • solutions/arm/processes/rps-payment-processing.md — RPS (Recurring Payment Schedule) payment processing for credit card (eway) and direct debit (ABA file), including status lifecycle and monitoring.
  • solutions/arm/processes/payment-method-change.md — Procedure for changing a parent's payment method before and after invoice generation, including the "Paid from Portal" protection mechanism.
  • meetings/2026-02-17-feoda-process-updates/transcript.txt — Plain-text transcript extracted from meeting recording (72,914 chars).
  • meetings/2026-02-17-feoda-process-updates/frames/ — 519 video frames extracted at 10-second intervals for reference.

Updated

  • solutions/arm/overview.md — Upgraded from draft to approved. Added the 4×4 Framework, expanded features table (Billing Configurator, RPS, Payment Suitelet, Portal Integration), added payment channels table, process documentation links, and active implementations comparison.
  • company/glossary.md — Added 16 new terms: ABA, B Pay, Billing Configurator, Billing Order, Central, Customer Deposit, Debtor, Edstart, eway, Family Billing Profile, OTP, RPS, Suitelet, Undeposited Funds, plus updated definitions for ARM and Billing Instructions.

[2026-02-18] - Documentation Project Initialized

Added

  • PROJECT_INSTRUCTIONS.md — Master governance document covering folder structure, naming conventions, writing style, Markdown conventions, frontmatter standard, template policy, client documentation rules, change governance & consistency protocol, contribution workflow, review & ownership model, versioning, and future considerations.
  • README.md — Repository landing page with navigation guide.
  • CHANGELOG.md — This file.
  • templates/ — 7 reusable document templates: solution-overview, process-document, meeting-extraction, technical-spec, runbook, decision-record, client-implementation.
  • company/ — Company-level documentation scaffold: about-feoda.md (seeded from feoda.ae), glossary.md (initial terms), onboarding/, processes/, policies/.
  • solutions/ — Solution documentation scaffold: erp/, arm/, epm/ with overview placeholders.
  • clients/ — Client implementation scaffold with _template/ skeleton (overview, requirements, design, customizations, testing, deployment, support).
  • tech/ — Technical documentation scaffold: architecture/, development/, netsuite/, frontend/, infrastructure/, runbooks/, decisions/.
  • meetings/ — Meeting extraction folder.