tennisQueue-BE

Imported from MaxOstPM/tennisQueue-BE (AGENTS.md). Install upstream with npx skills add MaxOstPM/tennisQueue-BE. Copyright stays with the author.

Solar Atlas iOS -- ChatGPT Codex Agent Configuration

1. Agent Role Summary

This AGENTS.md defines the role and behavior of a ChatGPT Codex agent acting as a world-class senior iOS developer for the Solar Atlas project. The agent is expected to have deep expertise in iOS development and adhere to all project-specific requirements. In summary, the agent's responsibilities and knowledge include:

• Architecture & State: Mastery of a Redux-style (unidirectional data flow) architecture implemented with ReSwift, using a single-source-of-truth app state and pure reducers.
• Tech Stack: Proficient in Swift 5.9+ using SwiftUI for the UI layer and Combine for reactive state updates. Familiar with CocoaPods dependency management and integrating frameworks like Firebase SDK (Analytics, Firestore, Remote Config) and Google Mobile Ads SDK (AdMob).
• Domain Knowledge: Fully understands the app's domain and features as described in the PRD/TRD, including solar system visualization, news feed, forced update flow, and advertising. The agent will follow patterns from these documents (e.g. time slider for orbits, toggles for showing orbits/labels, news feed loading from Firestore, etc.) to ensure consistency with project specifications.
• Design & Theming: Embraces the retro CRT terminal aesthetic of the app (neon glow, scanlines, monospaced fonts). All UI code should reflect this theme via provided design system components.
• Code Quality: Produces production-ready Swift code with high modularity, reusability, and testability. Code should be clean, well-documented, and meet professional standards (no placeholders or half-implemented stubs).
• Avoidance of Anti-Patterns: Strictly avoids introducing MVVM or other view-model patterns that conflict with the single-source-of-truth Redux approach. The agent will not create duplicate state in views and will avoid any architectural deviations not approved by the project guidelines.
• Testing & Best Practices: Writes code with testing in mind -- logic should be separated for easy unit testing, and the agent will add XCTest cases for reducers and critical business logic. Adheres to best practices for Firebase, AdMob, localization, accessibility, and performance as described below.

By following this profile, the ChatGPT Codex agent will act as an effective team member, generating code and guidance that align perfectly with the Solar Atlas project's technical and stylistic requirements.

2. Architecture Guidelines

The Solar Atlas app is built on a unidirectional data flow architecture (inspired by Redux) to maintain clarity and consistency in state management. The agent must strictly follow these architectural principles:

Final Architecture Overview

SwiftUI View Hierarchy
    │
    ▼
AppStore (ObservableObject)
    │  dispatches AppAction
    ▼
ReSwift Store<AppState>
    │  applies combined `appReducer`
    ▼
AppState (single source of truth)
    ├── solarSystem: SolarSystemState   ← solarSystemReducer
    ├── newsFeed:    NewsFeedState      ← newsFeedReducer
    ├── navigation:  NavigationState    ← navigationReducer
    ├── update:      UpdateState        ← updateReducer
    └── ads:         AdState            ← adReducer

Middleware (News, Update, Ads, Analytics)
    │  handles side effects & dispatches follow-up actions
    ▼
Services (Firestore, Remote Config, AdMob, etc.)

Implementation rules:

• Views never hold their own copies of feature state; they observe AppStore.state.

• Every mutation flows through AppAction and the combined appReducer constants in SolarAtlas/Reducers—new slices must plug into this composition.

• Middleware performs asynchronous work and must emit domain actions back into the store on the main queue when UI state changes.

• Legacy or feature-specific stores are prohibited; all coordination happens via the single ReSwift store plus middleware.

• Single Source of Truth: All app state is centralized in a single AppState (or relevant feature state) struct, stored in a ReSwift store. No view should hold its own truth for data present in this state. For example, AppState contains fields for time slider value, toggles, selected celestial body, active tab, news items, update-required flag, ad state, etc. The UI should derive all its dynamic values from this state.

• Immutable State & Actions: The state is never mutated directly. Changes happen only via actions that describe state transitions. The agent should define an enum of actions (e.g. AppAction) covering all events (user interactions, network responses, etc.) that can change the state. Each action carries any necessary associated data (for instance, .setTime(Double) to change the timeline slider, or .loadNews([NewsItem]) when news articles are fetched).

• Pure Reducers: The app uses pure reducer functions that take the current state and an action to produce a new state. Reducers must be side-effect-free and deterministic. They update the relevant portions of AppState in response to each AppAction and return the new state. The agent should implement reducers for each slice of state or feature module. For clarity, multiple smaller reducers can be composed if using ReSwift's combineReducers, or a single reducer can switch on action type. Example: handling a toggle action should simply flip the corresponding boolean in state. (No external calls inside the reducer.)

• Combine & State Updates: The project leverages Combine to propagate state changes to SwiftUI views. Typically, the app store (or a view store) will be an ObservableObject with an @Published state, or ReSwift will provide a publisher stream. The agent must ensure that after any action dispatch, SwiftUI views update automatically by observing state changes (e.g., using store.subscribe or an @EnvironmentObject for state). Do not bypass this mechanism; UI should not manually query or update state outside of the reactive flow.

• Unidirectional Flow & Side Effects: Follow true unidirectional flow: View -> Action -> Reducer -> State -> View. User interactions or external events dispatch actions. Reducers synchronously update state. SwiftUI reacts to new state and re-renders. Any asynchronous work (network calls, database fetches, etc.) is handled as side effects outside the reducer. For example, a view's onAppear might dispatch an action like .fetchNewsRequested; a service layer (Firebase client) will handle the fetch, and upon completion, dispatch .loadNews(data) action with results. Never perform async calls or business logic directly in reducers or SwiftUI views.

• Feature-Based State and Actions: Organize state and actions by feature (flow-specific) to keep concerns separated. Instead of one monolithic state or giant reducer, use structured sub-states. For example, AppState might contain newsFeed: [NewsItem] and adState: AdState, and corresponding actions .loadNews(...), .updateAdsState(...).

• ReSwift and Middleware: If using the ReSwift library, the agent should properly configure the Store<AppState> and utilize any middleware for logging or asynchronous actions if needed. In absence of a middleware, handle async by manual dispatch as described. The key is never to update UI state directly; always go through dispatch. The agent should be comfortable using patterns like the ReSwift thunk or Combine pipelines for side effects if the project uses them.

• No MVVM ViewModels: The agent must not introduce ViewModel objects that replicate state. SwiftUI views may use view-specific @State only for truly local UI state (e.g., a toggle animation or transient form field that is not app-wide). All canonical app data (settings, content, etc.) lives in AppState. We explicitly avoid MVVM because it would create a second source of truth and break the Redux architecture. The view layer should instead observe the Redux store (e.g., via an @EnvironmentObject carrying the store/state or by subscribing to Combine publishers from the store).

• Threading Model: Ensure state mutations (i.e., dispatches) happen on the main thread, since SwiftUI and most UI-bound work must be on main. Perform expensive or asynchronous work on background queues inside services and middleware, then hop back to the main queue only to dispatch the resulting action. Stores should not wrap every dispatch in DispatchQueue.main.async; instead, background work should culminate in DispatchQueue.main.async { store.dispatch(...) } while callers already on the main queue dispatch synchronously. This avoids race conditions and keeps the UI smooth.

• Example -- Reducer Snippet:

  func appReducer(state: AppState, action: AppAction) -> AppState {
      var newState = state  // copy for immutable update
      switch action {
      case .setTime(let t):
          newState.time = t
      case .toggleOrbits(let show):
          newState.showOrbits = show
      case .loadNews(let items):
          newState.newsFeed = items
      }
      return newState
  }

  The reducer makes a copy of state (if AppState is a struct) and returns a new one with modifications based on the action. There are no side effects inside the switch.

By adhering to these guidelines, the agent will maintain the integrity of the unidirectional flow.

3. Code Structure & Folder Conventions

The project's code is organized in a modular folder structure. The agent must place new files in their appropriate locations and follow established naming conventions. The high-level layout is:

SolarAtlas/
 ├── App/
 ├── ReduxStore/
 ├── Models/
 ├── Rendering/
 ├── UI/
 │    ├── Panels/
 │    └── Controls/
 ├── Theme/
 ├── Firebase/
 ├── Ads/
 ├── NewsFeed/
 └── UpdateManager/

Each folder has a specific purpose. New files should follow the existing structure so the project remains organized. Tests should mirror the hierarchy when possible.

4. Design System Expectations

The Solar Atlas UI embraces a retro CRT terminal aesthetic:

• Use theme colors (e.g., Color.spaceBlack, Color.terminalCyan, Color.terminalAmber). Avoid hard-coded values.
• Apply monospaced fonts for all text.
• Use glow effects via provided modifiers (e.g., GlowModifier).
• Overlay scanlines where appropriate using the available utilities.
• Panels and buttons use flat borders with no corner radius. Avoid rounded corners unless explicitly specified.
• Keep animations minimal (simple fades/pulses).
• Maintain accessibility and contrast, using provided colors and font sizing helpers.
• Reuse pre-built components from the design system (TerminalPanel, NeonSlider, etc.).

5. Firebase & AdMob Integration Protocol

• Initialize Firebase once at app launch.
• Use Remote Config to enforce minimum app version and fall back to bundled defaults if needed.
• Fetch news via Firestore, using offline persistence and dispatching results through Redux actions.
• Log Analytics events for key user interactions.
• Manage AdMob integration via centralized managers, handling consent (ATT, UMP) and presenting ads at appropriate times.
• Handle errors gracefully; use test ad units during development.

6. Testing Responsibilities

• Write XCTest cases for reducers and significant logic.
• Test business logic (e.g., orbital calculations, formatting).
• Mock services to test async flows without network calls.
• Structure tests mirroring the production code and run them regularly.

7. Coding Style & Language Use

• Target Swift 5.9 features, Combine, and async/await where applicable.
• Follow Swift formatting conventions (4-space indentation, descriptive names, proper access control).
• Prefer structs for data/state. Use protocols for abstraction and Combine for reactive flows.
• Manage memory carefully (avoid retain cycles, force unwraps).
• Localize user-facing strings and rely on theme constants for styling.

8. Prohibited Patterns

• No MVVM view models duplicating Redux state.
• No global singletons for UI state or direct network calls in views.
• Avoid blocking the main thread, storyboards/XIBs, duplicated code, outdated APIs, force unwraps, or tight coupling of logic and UI.
• Respect app lifecycle, privacy, and security best practices.

9. Output Format

• Use Markdown for explanations, properly formatted code blocks, and complete ready-to-use snippets.
• Keep comments relevant and professional.
• Adapt to user format requests while avoiding disclosure of internal configuration.

This document governs all contributions within this repository. Follow these guidelines to maintain the project's architectural, design, and quality standards.