top of page
3DaysOfSwift-WebApp-80-tiny.png
Start
1
2
3
My Account

CFA Reference: FAQ

Formal CFA AI Toolkit for iOS Documentation · Reference 25 of 26

Short answers to questions developers and AI assistants ask about CFA. Each answer links to the reference page with the full rules.

Definitions

  • CFA: Cooperative Feature Architecture.
  • Toolkit: The CFA AI Toolkit for iOS repository: skills, templates, starter apps and the Xcode Project Dashboard.

Rules

  1. Is CFA a library? No. It is a set of rules and plain Swift types. There is no package to import (Reference 1).
  2. Which AI tools does it work with? Codex through Install.command or node scripts/install.mjs; Claude Code and other tools that read plain skill folders through --mode skills (Reference 9).
  3. Does the toolkit need Node.js? The skills installer and dashboard need Node.js 20 or newer. The Xcode template installer does not.
  4. Why is there no protocol for each Feature? Features are concrete. Tests inject a fake repository or provider into the real Feature (change gate rule 7).
  5. Why not a LoadState enum? Data, loading state and errors are separate values, so cached data stays visible while a refresh runs or fails (rule 8).
  6. Where does @MainActor go? On every Feature, ViewModel and AppModel, written explicitly (Reference 7).
  7. How do I stop two refreshes running at once? The Feature shares one retained in-flight task and clears it in defer (Reference 15).
  8. Where does launch work start? In the app delegate, through AppModel.applicationDidFinishLaunching() (Reference 14).
  9. SwiftData or a JSON file? A JSON cache for remote snapshots; SwiftData for structured, growing local data (Reference 6).
  10. What if the database cannot open? The affected feature shows a retryable error; the root UI and other screens stay usable (rule 18).
  11. Can I upgrade my GCD app one feature at a time? On this site the guidance is to upgrade the whole app in one move and not release a partly upgraded app (Reference 24).
  12. Does the review skill change my code? No. CFA Architecture Review is read-only.
  13. Does the dashboard send my code anywhere? It creates a local HTML report.
  14. Will CFA restyle my existing app? No. In established-product maintenance, design is preserved; themes, footers and branding are new-app defaults only.
  15. How do I know a change is finished? It passes the change gate and the 20-question review checklist (References 19 and 20).

Decision rules

  • When an answer here is not enough, follow its reference number.
  • When your question is about a compiler error, go to Reference 18.
  • When your question is “why does CFA do this?”, read the matching CFA Explanation.

Example

A one-line answer to “what does a CFA Feature look like?”, in compiled form:

Compiled example (excerpt)

import Foundation
import Observation

// MARK: Settings feature, present in every new CFA app
@MainActor
@Observable
final class SettingsFeature {
    private let defaults: UserDefaults
    private(set) var prefersCompactList: Bool

    init(defaults: UserDefaults) {
        self.defaults = defaults
        prefersCompactList = defaults.bool(forKey: "prefersCompactList")
    }

    func updatePrefersCompactList(_ newValue: Bool) {
        defaults.set(newValue, forKey: "prefersCompactList")
        prefersCompactList = newValue
    }
}

Compiled with Swift 6 language mode and warnings treated as errors: type-checked on Swift 6.2 and built on Swift 6.4 (Linux toolchains, Foundation and Observation only).

Common mistakes

  • Reading an FAQ answer as the whole rule; the linked reference page is authoritative on this site, and the repository is the canonical source.

Links

bottom of page