docs: Document the demo app better

ConfidenceDemoApp/ConfidenceDemoApp/ConfidenceDemoApp.swift

@@ -26,11 +26,12 @@ struct ConfidenceDemoApp: App {
             .withContext(initialContext: context)
             .build()
         do {
-            // DANGER: here we are activating anything in storage, could be data of a different user 
-            try confidence.activate() // Activating the existing cache, in case the new fetch fails i.e. offline mode
+            // NOTE: here we are activating all the flag values from storage, regardless of how `context` looks now
+            try confidence.activate()
         } catch {
             flaggingState.state = .error(ExperimentationFlags.CustomError(message: error.localizedDescription))
         }
+        // flaggingState.color is set here at startup and remains immutable until a user logs out
         flaggingState.color = ContentView.getColor(
             color: confidence.getValue(
                 key: "swift-demoapp.color",
@@ -59,7 +60,9 @@ struct ConfidenceDemoApp: App {
         Task {
             do {
                 flaggingState.state = .loading
-                try await Task.sleep(nanoseconds: 2 * 1_000_000_000)
+                try await Task.sleep(nanoseconds: 2 * 1_000_000_000) // simulating slow network
+                // The flags in storage are refreshed for the current `context`, and activated
+                // After this line, fresh (and potentially new) flags values can be accessed
                 try await confidence.fetchAndActivate()
                 flaggingState.state = .ready
             } catch {

ConfidenceDemoApp/ConfidenceDemoApp/ContentView.swift

@@ -35,10 +35,16 @@ struct ContentView: View {
                         Spacer()
                         if let user = loggedUser {
                             let eval = confidence.getEvaluation(key: "swift-demoapp.color", defaultValue: "Gray")
-                            Text("Hello \(user)")
-                                .font(.largeTitle)
-                                .foregroundStyle(ContentView.getColor(color: eval.value))
-                                .padding()
+                            VStack {
+                                Text("Hello \(user)")
+                                    .font(.largeTitle)
+                                    .foregroundStyle(ContentView.getColor(color: eval.value))
+                                    .padding()
+                                Text("This text only appears after a successful flag fetching")
+                                    .font(.caption)
+                                    .foregroundStyle(ContentView.getColor(color: eval.value))
+                                    .padding()
+                            }
                         }
                     }
                 }
@@ -64,16 +70,16 @@ struct ContentView: View {
             ZStack {
                 VStack {
                     Spacer()
-                    Text("This text is set on onAppear, doesn't wait for reconciliation")
+                    Text("This text color is set on onAppear, doesn't wait for flag fetch")
                         .font(.caption)
                         .foregroundStyle(textColor)
-                    Text("This text dynamically changes on flags fetch")
+                    Text("This text color dynamically changes on each flags fetch")
                         .font(.caption)
                         .foregroundStyle(ContentView.getColor(
                             color: confidence.getValue(
                                 key: "swift-demoapp.color",
                                 defaultValue: "Gray")))
-                    Text("This text is fixed from user session start, and before any flags fetch")
+                    Text("This text color is fixed from app start, doesn't react on flag fetches")
                         .font(.caption)
                         .foregroundStyle(flaggingState.color)
                 }
@@ -101,6 +107,6 @@ struct ContentView: View {
 
 struct AboutPage: View {
     var body: some View {
-        Text("About Page")
+        Text("Mock Page")
     }
 }

ConfidenceDemoApp/ConfidenceDemoApp/LoginView.swift

@@ -35,18 +35,19 @@ struct LoginView: View {
                         color: confidence.getValue(key: "swift-demoapp.color", defaultValue: "Gray")
                     )
 
-                    // Load flags
+                    // Simulating a module that handles feature flagging state during login
                     Task {
                         flaggingState.state = .loading
-                        try? await Task.sleep(nanoseconds: 5 * 1_000_000_000)
+                        try? await Task.sleep(nanoseconds: 5 * 1_000_000_000) // simulating network delay
+                        // putContext adds the user_id field to the evaluation context and fetches values for it
                         await confidence.putContext(context: ["user_id": .init(string: "user1")])
                         flaggingState.state = .ready
                     }
 
-                    // Load everything else for this user
+                    // Simulating a module that handles the actual login mechanism for a user
                     Task {
                         loggingIn = true
-                        try? await Task.sleep(nanoseconds: 1 * 1_000_000_000)
+                        try? await Task.sleep(nanoseconds: 1 * 1_000_000_000) // simulating network delay
                         loggedUser = "user1"
                         loggingIn = false
                         loginCompleted = true