Skip to content

0020: Project ADA Phase 1 - AI Credit Model and Business Alignment

  • Status: ✅ Accepted
  • Date: 2026-07-31 (proposed 2026-07-30; accepted 2026-07-31)
  • Owners: Özcan Övünç, Osman Çelik
  • Context: Project ADA brings the first AI capability into the Appcircle product: the AI Build Error Interpreter. The technical design is settled in the Phase 1 TDD; this ADR records the business decisions that go with it.

Business Alignments

  • One shared AI credit pool. All AI features draw from a single per-organization credit balance rather than a per-feature entitlement, and every AI call costs a flat 1 credit. The balance is a monthly allowance that resets each month; unused credits do not carry over.

  • Credits are charged only after a successful analysis, and asynchronously. A failed analysis costs nothing, and the charge travels over a Kafka event rather than the request itself, so the balance is eventually consistent (a couple of near-simultaneous requests can slip one analysis past the limit). We accept this: the overshoot is at most one analysis and self-corrects.

  • Charging is per failed step, not per build. A build with three failed steps costs three credits, because the user analyzes each step separately.

  • One analysis per failed step, no re-run. A (build, step) pair is analyzed exactly once, so a second click is free but also means an unhelpful answer cannot be retried; the only fresh analysis is a new build run.

  • Every account starts with 2 credits when the feature goes live. Both Starter and Enterprise plans default to a monthly allowance of 2 credits, so every organization can try the feature at a small scale without a manual grant.

  • A 0 balance hides the feature entirely. The credit allowance doubles as the feature flag: at 0 (or unset) no AI action is rendered anywhere in the product, and any value above 0 turns the feature on with that monthly allowance. There is no separate on/off switch to maintain.

  • Access is granted manually, per company, by Osman Çelik. After go-live he decides which organizations get the feature, and we set their monthly allowance (e.g. 100 credits) by hand from the internal admin panel. This is a pilot allowlist and is independent of plan tier.

  • Only an Organization Management > Manager (or the org Owner) can accept the AI consent. Consent is recorded once per organization; after it is accepted, anyone in that organization who already has the build permissions can run an analysis, since AI analysis inherits build access rather than defining its own roles. A member without the manager role who presses Accept gets the platform's standard "Access denied. Please contact your administrator." message.

  • Product owns the AI FAQ document, and it is a launch blocker. The consent popup is short and links to a public FAQ page that carries the full text, including the disclaimers (anonymization is best effort with no 100% guarantee, and the cloud offering sends anonymized content to Anthropic and Langfuse). The frontend links to that page, so the feature cannot ship before it exists.

  • Cloud only, and shipped as Beta. Self-hosted and air-gapped customers do not get this feature in Phase 1, and the feature is labeled Beta running on Appcircle's own Anthropic plan; bring-your-own-model comes later.

  • Anonymized build log content leaves our perimeter. Only anonymized content is sent, Langfuse stores it in its EU region, and this was reviewed as GDPR compliant, but it is a customer-facing data statement.