gaia-framework 1.57.0 → 1.57.2

package/_gaia/dev/knowledge/java/spring-boot-patterns.md

@@ -1,160 +0,0 @@
----
-name: Spring Boot Patterns
-stack: java
-version: "1.0"
-focus: [spring-boot]
----
-
-# Spring Boot Patterns
-
-## Principle
-
-Leverage Spring Boot's auto-configuration and convention-over-configuration philosophy. Use constructor injection for mandatory dependencies, profiles for environment-specific configuration, and Actuator for production observability. Structure applications in layers (controller, service, repository) with clear dependency direction.
-
-## Rationale
-
-Spring Boot eliminates boilerplate by auto-configuring beans based on classpath contents. Constructor injection makes dependencies explicit and immutable, and enables testing without the Spring container. Profiles allow the same codebase to run against different environments without code changes. Actuator provides production-ready health checks, metrics, and management endpoints with zero custom code.
-
-## Pattern Examples
-
-### Pattern 1: Layered Architecture with Constructor Injection
-
-```java
-// Controller — thin, delegates to service
-@RestController
-@RequestMapping("/api/v1/users")
-@RequiredArgsConstructor  // Lombok generates constructor
-public class UserController {
-
-    private final UserService userService;
-
-    @GetMapping
-    public ResponseEntity<List<UserDto>> getAll(
-            @RequestParam(defaultValue = "0") int page,
-            @RequestParam(defaultValue = "20") int size) {
-        var users = userService.findAll(PageRequest.of(page, size));
-        return ResponseEntity.ok(users.getContent());
-    }
-
-    @PostMapping
-    public ResponseEntity<UserDto> create(@Valid @RequestBody CreateUserRequest request) {
-        var user = userService.create(request);
-        var uri = URI.create("/api/v1/users/" + user.id());
-        return ResponseEntity.created(uri).body(user);
-    }
-}
-
-// Service — business logic
-@Service
-@RequiredArgsConstructor
-@Transactional(readOnly = true)
-public class UserService {
-
-    private final UserRepository userRepository;
-    private final UserMapper userMapper;
-
-    public Page<UserDto> findAll(Pageable pageable) {
-        return userRepository.findAll(pageable).map(userMapper::toDto);
-    }
-
-    @Transactional
-    public UserDto create(CreateUserRequest request) {
-        var entity = userMapper.toEntity(request);
-        var saved = userRepository.save(entity);
-        return userMapper.toDto(saved);
-    }
-}
-```
-
-### Pattern 2: Profile-Based Configuration
-
-```yaml
-# application.yml — common settings
-spring:
-  application:
-    name: user-service
-  jpa:
-    open-in-view: false
-
----
-# application-dev.yml
-spring:
-  config:
-    activate:
-      on-profile: dev
-  datasource:
-    url: jdbc:h2:mem:devdb
-  jpa:
-    show-sql: true
-
----
-# application-prod.yml
-spring:
-  config:
-    activate:
-      on-profile: prod
-  datasource:
-    url: jdbc:postgresql://${DB_HOST}:5432/users
-  jpa:
-    show-sql: false
-```
-
-```java
-// Profile-conditional bean
-@Configuration
-public class CacheConfig {
-
-    @Bean
-    @Profile("prod")
-    public CacheManager redisCacheManager(RedisConnectionFactory factory) {
-        return RedisCacheManager.builder(factory).build();
-    }
-
-    @Bean
-    @Profile("!prod")
-    public CacheManager simpleCacheManager() {
-        return new ConcurrentMapCacheManager("users");
-    }
-}
-```
-
-### Pattern 3: Actuator and Custom Health Indicator
-
-```java
-@Component
-@RequiredArgsConstructor
-public class DatabaseHealthIndicator implements HealthIndicator {
-
-    private final DataSource dataSource;
-
-    @Override
-    public Health health() {
-        try (var conn = dataSource.getConnection()) {
-            if (conn.isValid(2)) {
-                return Health.up()
-                    .withDetail("database", "reachable")
-                    .build();
-            }
-        } catch (SQLException e) {
-            return Health.down()
-                .withDetail("error", e.getMessage())
-                .build();
-        }
-        return Health.down().build();
-    }
-}
-```
-
-## Anti-Patterns
-
-- **Field injection with `@Autowired`**: Hides dependencies, prevents immutability, and complicates testing. Use constructor injection.
-- **Business logic in controllers**: Controllers should validate input and delegate. Logic belongs in the service layer.
-- **`spring.jpa.open-in-view=true` (default)**: Keeps DB sessions open during view rendering, causing lazy-loading surprises and connection pool exhaustion. Set to `false`.
-- **Catching all exceptions in each controller method**: Use `@ControllerAdvice` with `@ExceptionHandler` for centralized error handling.
-
-## Integration Points
-
-- **JPA**: Repository layer uses Spring Data JPA; see `jpa-patterns.md` for entity mapping and query optimization.
-- **Microservices**: Spring Boot apps are the unit of deployment; see `microservices.md` for service decomposition.
-- **Build Tools**: Spring Boot plugin integrates with Maven/Gradle; see `maven-gradle.md`.
-- **Testing**: Use `@SpringBootTest` for integration tests, plain JUnit for service unit tests.

package/_gaia/dev/knowledge/mobile/kotlin-patterns.md

@@ -1,193 +0,0 @@
----
-name: Kotlin Android Patterns
-stack: mobile
-version: "1.0"
-focus: [kotlin]
----
-
-# Kotlin Android Patterns
-
-## Principle
-
-Use Kotlin coroutines (Flow, StateFlow) for reactive data streams, Jetpack Compose for declarative UI, Hilt for dependency injection, and sealed classes for modeling finite state. Structure Android apps with MVVM architecture where ViewModels expose UI state as StateFlow and Compose observes it.
-
-## Rationale
-
-Coroutines provide structured concurrency that respects lifecycle boundaries, preventing common memory leaks and crashes from orphaned async work. `StateFlow` is a hot stream that always holds a current value, making it ideal for UI state. Jetpack Compose replaces XML layouts with a reactive, composable UI framework similar to SwiftUI and Flutter. Hilt simplifies Dagger-based DI with Android-specific lifecycle-aware scoping.
-
-## Pattern Examples
-
-### Pattern 1: ViewModel with StateFlow
-
-```kotlin
-// UI State — sealed interface for exhaustive when()
-sealed interface UserListState {
-    data object Loading : UserListState
-    data class Success(val users: List<User>) : UserListState
-    data class Error(val message: String) : UserListState
-}
-
-@HiltViewModel
-class UserListViewModel @Inject constructor(
-    private val userRepository: UserRepository,
-) : ViewModel() {
-
-    private val _state = MutableStateFlow<UserListState>(UserListState.Loading)
-    val state: StateFlow<UserListState> = _state.asStateFlow()
-
-    init {
-        loadUsers()
-    }
-
-    fun loadUsers() {
-        viewModelScope.launch {
-            _state.value = UserListState.Loading
-            userRepository.getUsers()
-                .catch { e ->
-                    _state.value = UserListState.Error(
-                        e.message ?: "Unknown error"
-                    )
-                }
-                .collect { users ->
-                    _state.value = UserListState.Success(users)
-                }
-        }
-    }
-}
-```
-
-### Pattern 2: Jetpack Compose UI
-
-```kotlin
-@Composable
-fun UserListScreen(
-    viewModel: UserListViewModel = hiltViewModel(),
-) {
-    val state by viewModel.state.collectAsStateWithLifecycle()
-
-    Scaffold(
-        topBar = {
-            TopAppBar(title = { Text("Users") })
-        },
-    ) { padding ->
-        when (val s = state) {
-            is UserListState.Loading -> {
-                Box(
-                    modifier = Modifier.fillMaxSize().padding(padding),
-                    contentAlignment = Alignment.Center,
-                ) {
-                    CircularProgressIndicator()
-                }
-            }
-            is UserListState.Success -> {
-                LazyColumn(
-                    contentPadding = padding,
-                    verticalArrangement = Arrangement.spacedBy(8.dp),
-                ) {
-                    items(
-                        items = s.users,
-                        key = { it.id },
-                    ) { user ->
-                        UserCard(user = user)
-                    }
-                }
-            }
-            is UserListState.Error -> {
-                ErrorView(
-                    message = s.message,
-                    onRetry = viewModel::loadUsers,
-                    modifier = Modifier.padding(padding),
-                )
-            }
-        }
-    }
-}
-
-@Composable
-fun UserCard(user: User, modifier: Modifier = Modifier) {
-    Card(
-        modifier = modifier.fillMaxWidth().padding(horizontal = 16.dp),
-    ) {
-        Row(
-            modifier = Modifier.padding(16.dp),
-            verticalAlignment = Alignment.CenterVertically,
-        ) {
-            AsyncImage(
-                model = user.avatarUrl,
-                contentDescription = null,
-                modifier = Modifier.size(48.dp).clip(CircleShape),
-            )
-            Spacer(modifier = Modifier.width(12.dp))
-            Column {
-                Text(user.name, style = MaterialTheme.typography.titleMedium)
-                Text(user.email, style = MaterialTheme.typography.bodySmall)
-            }
-        }
-    }
-}
-```
-
-### Pattern 3: Hilt Dependency Injection
-
-```kotlin
-// Module providing dependencies
-@Module
-@InstallIn(SingletonComponent::class)
-object NetworkModule {
-
-    @Provides
-    @Singleton
-    fun provideOkHttpClient(): OkHttpClient {
-        return OkHttpClient.Builder()
-            .addInterceptor(AuthInterceptor())
-            .connectTimeout(30, TimeUnit.SECONDS)
-            .build()
-    }
-
-    @Provides
-    @Singleton
-    fun provideRetrofit(client: OkHttpClient): Retrofit {
-        return Retrofit.Builder()
-            .baseUrl(BuildConfig.API_BASE_URL)
-            .client(client)
-            .addConverterFactory(MoshiConverterFactory.create())
-            .build()
-    }
-
-    @Provides
-    @Singleton
-    fun provideUserApi(retrofit: Retrofit): UserApi {
-        return retrofit.create(UserApi::class.java)
-    }
-}
-
-// Repository with injected dependencies
-@Singleton
-class UserRepository @Inject constructor(
-    private val userApi: UserApi,
-    private val userDao: UserDao,
-) {
-    fun getUsers(): Flow<List<User>> = flow {
-        // Emit cached data first
-        emit(userDao.getAll())
-        // Then fetch fresh data
-        val remote = userApi.getUsers()
-        userDao.insertAll(remote)
-        emit(remote)
-    }
-}
-```
-
-## Anti-Patterns
-
-- **Collecting flows without lifecycle awareness**: Using `collect` directly in a coroutine scope without `repeatOnLifecycle` or `collectAsStateWithLifecycle` causes updates to be processed when the UI is not visible.
-- **Mutable state exposed from ViewModel**: Exposing `MutableStateFlow` instead of `StateFlow` allows views to mutate state directly.
-- **Recomposition-heavy Compose**: Passing unstable types to composables causes unnecessary recomposition. Use immutable data classes and `@Stable` annotation.
-- **Manual DI wiring**: Building dependency graphs by hand instead of using Hilt. Hilt handles scoping and lifecycle automatically.
-
-## Integration Points
-
-- **React Native**: Kotlin native modules bridge to React Native via TurboModules; see `react-native-patterns.md`.
-- **Mobile Testing**: JUnit, Compose testing, and Espresso; see `mobile-testing.md`.
-- **Swift**: Cross-platform design considerations; see `swift-patterns.md`.
-- **Coroutines**: `Flow` integrates with Room, Retrofit, and Compose seamlessly.

package/_gaia/dev/knowledge/mobile/mobile-testing.md

@@ -1,186 +0,0 @@
----
-name: Mobile Testing Strategies
-stack: mobile
-version: "1.0"
-focus: [mobile-testing]
----
-
-# Mobile Testing Strategies
-
-## Principle
-
-Test mobile apps at three levels: unit tests for business logic, component/widget tests for UI rendering, and end-to-end tests for critical user flows. Use platform-specific tools (XCTest, Espresso, Detox) for E2E, and cross-platform tools (Jest, flutter_test) for unit and component layers. Include screenshot testing to catch visual regressions across devices and OS versions.
-
-## Rationale
-
-Mobile apps run on diverse hardware (screen sizes, OS versions, chipsets) and are distributed as immutable binaries that cannot be hotfixed. This makes pre-release testing critical. Unit tests verify logic without simulators/emulators and run in seconds. Component tests verify UI rendering and interaction in isolation. E2E tests validate real user flows but are slower and flakier, so they should cover only critical paths. Screenshot testing catches subtle visual regressions that functional tests miss.
-
-## Pattern Examples
-
-### Pattern 1: React Native Testing with Detox
-
-```typescript
-// e2e/login.test.ts — Detox E2E test
-describe('Login Flow', () => {
-  beforeAll(async () => {
-    await device.launchApp({ newInstance: true });
-  });
-
-  beforeEach(async () => {
-    await device.reloadReactNative();
-  });
-
-  it('should log in with valid credentials', async () => {
-    await element(by.id('email-input')).typeText('user@example.com');
-    await element(by.id('password-input')).typeText('password123');
-    await element(by.id('login-button')).tap();
-
-    // Wait for navigation to complete
-    await waitFor(element(by.id('home-screen')))
-      .toBeVisible()
-      .withTimeout(5000);
-
-    await expect(element(by.text('Welcome back'))).toBeVisible();
-  });
-
-  it('should show error for invalid credentials', async () => {
-    await element(by.id('email-input')).typeText('wrong@example.com');
-    await element(by.id('password-input')).typeText('wrong');
-    await element(by.id('login-button')).tap();
-
-    await waitFor(element(by.id('error-message')))
-      .toBeVisible()
-      .withTimeout(3000);
-
-    await expect(element(by.text('Invalid credentials'))).toBeVisible();
-  });
-});
-
-// Component test with React Native Testing Library
-import { render, fireEvent, waitFor } from '@testing-library/react-native';
-
-test('LoginForm calls onSubmit with email and password', async () => {
-  const onSubmit = jest.fn();
-  const { getByTestId } = render(<LoginForm onSubmit={onSubmit} />);
-
-  fireEvent.changeText(getByTestId('email-input'), 'user@example.com');
-  fireEvent.changeText(getByTestId('password-input'), 'password123');
-  fireEvent.press(getByTestId('login-button'));
-
-  await waitFor(() => {
-    expect(onSubmit).toHaveBeenCalledWith({
-      email: 'user@example.com',
-      password: 'password123',
-    });
-  });
-});
-```
-
-### Pattern 2: iOS Testing with XCTest
-
-```swift
-// Unit test — pure logic, no UI
-class UserServiceTests: XCTestCase {
-    var sut: UserService!
-    var mockRepository: MockUserRepository!
-
-    override func setUp() {
-        super.setUp()
-        mockRepository = MockUserRepository()
-        sut = UserService(repository: mockRepository)
-    }
-
-    func testFetchUsersReturnsUsers() async throws {
-        mockRepository.stubbedUsers = [
-            User(id: "1", name: "Alice", email: "alice@test.com"),
-        ]
-
-        let users = try await sut.fetchAll()
-
-        XCTAssertEqual(users.count, 1)
-        XCTAssertEqual(users.first?.name, "Alice")
-    }
-}
-
-// UI test with XCUITest
-class LoginUITests: XCTestCase {
-    let app = XCUIApplication()
-
-    override func setUp() {
-        super.setUp()
-        continueAfterFailure = false
-        app.launchArguments = ["--uitesting"]
-        app.launch()
-    }
-
-    func testSuccessfulLogin() {
-        let emailField = app.textFields["email-field"]
-        let passwordField = app.secureTextFields["password-field"]
-        let loginButton = app.buttons["login-button"]
-
-        emailField.tap()
-        emailField.typeText("user@example.com")
-        passwordField.tap()
-        passwordField.typeText("password123")
-        loginButton.tap()
-
-        let homeScreen = app.staticTexts["Welcome back"]
-        XCTAssertTrue(homeScreen.waitForExistence(timeout: 5))
-    }
-}
-```
-
-### Pattern 3: Screenshot Testing
-
-```kotlin
-// Android — Compose screenshot test (Roborazzi)
-@RunWith(ParameterizedRobolectricTestRunner::class)
-class UserCardScreenshotTest(
-    private val config: ScreenConfig,
-) {
-    @get:Rule
-    val composeTestRule = createComposeRule()
-
-    @Test
-    fun userCard_default() {
-        composeTestRule.setContent {
-            AppTheme {
-                UserCard(
-                    user = User(
-                        name = "Alice Johnson",
-                        email = "alice@example.com",
-                        avatarUrl = null,
-                    ),
-                )
-            }
-        }
-        composeTestRule.onRoot()
-            .captureRoboImage("screenshots/user_card_${config.name}.png")
-    }
-
-    companion object {
-        @JvmStatic
-        @ParameterizedRobolectricTestRunner.Parameters(name = "{0}")
-        fun configs() = listOf(
-            ScreenConfig("phone", 360, 640, 2f),
-            ScreenConfig("tablet", 800, 1280, 2f),
-            ScreenConfig("phone_large_font", 360, 640, 2f, fontScale = 1.5f),
-        )
-    }
-}
-```
-
-## Anti-Patterns
-
-- **E2E tests for everything**: E2E tests are slow and flaky. Use them only for critical user flows (login, checkout, onboarding). Test business logic with unit tests.
-- **No testIDs on interactive elements**: Without accessibility IDs (`testID` in RN, `accessibilityIdentifier` in iOS), E2E tests rely on fragile text matchers.
-- **Testing implementation details**: Testing internal state or private methods couples tests to implementation. Test behavior and outputs.
-- **Skipping device matrix testing**: Testing only on one device/OS version misses platform-specific rendering bugs.
-- **No screenshot baseline management**: Screenshot tests without proper baseline storage and diff tooling generate false positives.
-
-## Integration Points
-
-- **React Native**: Detox and RNTL for cross-platform testing; see `react-native-patterns.md`.
-- **Swift**: XCTest and XCUITest for iOS; see `swift-patterns.md`.
-- **Kotlin**: JUnit, Compose Test, and Espresso for Android; see `kotlin-patterns.md`.
-- **CI/CD**: Run unit/component tests on every PR; E2E tests nightly or on release branches.

package/_gaia/dev/knowledge/mobile/react-native-patterns.md

@@ -1,162 +0,0 @@
----
-name: React Native Application Patterns
-stack: mobile
-version: "1.0"
-focus: [react-native]
----
-
-# React Native Application Patterns
-
-## Principle
-
-Build cross-platform mobile apps with React Native using platform-aware component composition, optimized list rendering with `FlatList`, and React Navigation for type-safe navigation. Use the Hermes engine for improved startup performance and the new architecture (Fabric, TurboModules) for better native interop.
-
-## Rationale
-
-React Native bridges JavaScript and native platforms, so performance-sensitive code must account for the bridge overhead. `FlatList` virtualizes long lists, rendering only visible items. React Navigation provides a native-feeling navigation experience with proper gesture handling. Hermes (default since RN 0.70) pre-compiles JavaScript to bytecode, reducing TTI by 30-50%. The new architecture eliminates the async bridge bottleneck with synchronous native calls.
-
-## Pattern Examples
-
-### Pattern 1: Optimized FlatList with Memoized Items
-
-```typescript
-interface Message {
-  id: string;
-  text: string;
-  sender: string;
-  timestamp: number;
-}
-
-const MessageItem = memo(function MessageItem({
-  item,
-  onPress,
-}: {
-  item: Message;
-  onPress: (id: string) => void;
-}) {
-  const handlePress = useCallback(() => onPress(item.id), [item.id, onPress]);
-
-  return (
-    <Pressable onPress={handlePress} style={styles.messageItem}>
-      <Text style={styles.sender}>{item.sender}</Text>
-      <Text style={styles.text}>{item.text}</Text>
-    </Pressable>
-  );
-});
-
-function MessageList({ messages }: { messages: Message[] }) {
-  const handlePress = useCallback((id: string) => {
-    // Handle message press
-  }, []);
-
-  const renderItem = useCallback(
-    ({ item }: { item: Message }) => (
-      <MessageItem item={item} onPress={handlePress} />
-    ),
-    [handlePress]
-  );
-
-  const keyExtractor = useCallback((item: Message) => item.id, []);
-
-  return (
-    <FlatList
-      data={messages}
-      renderItem={renderItem}
-      keyExtractor={keyExtractor}
-      initialNumToRender={15}
-      maxToRenderPerBatch={10}
-      windowSize={5}
-      removeClippedSubviews
-      getItemLayout={(_, index) => ({
-        length: ITEM_HEIGHT,
-        offset: ITEM_HEIGHT * index,
-        index,
-      })}
-    />
-  );
-}
-```
-
-### Pattern 2: Type-Safe React Navigation
-
-```typescript
-import { NavigationContainer } from '@react-navigation/native';
-import { createNativeStackNavigator } from '@react-navigation/native-stack';
-import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
-
-// Define all route params in one place
-type RootStackParamList = {
-  Auth: undefined;
-  Main: undefined;
-};
-
-type MainTabParamList = {
-  Home: undefined;
-  Profile: { userId: string };
-  Settings: undefined;
-};
-
-type HomeStackParamList = {
-  Feed: undefined;
-  PostDetail: { postId: string };
-};
-
-const RootStack = createNativeStackNavigator<RootStackParamList>();
-const MainTab = createBottomTabNavigator<MainTabParamList>();
-const HomeStack = createNativeStackNavigator<HomeStackParamList>();
-
-// Type-safe navigation in components
-import { NativeStackScreenProps } from '@react-navigation/native-stack';
-
-type PostDetailProps = NativeStackScreenProps<HomeStackParamList, 'PostDetail'>;
-
-function PostDetailScreen({ route, navigation }: PostDetailProps) {
-  const { postId } = route.params;  // TypeScript knows postId is string
-  // navigation.navigate('Feed') works; navigate('Invalid') is a type error
-  return <PostView postId={postId} />;
-}
-```
-
-### Pattern 3: Platform-Specific Code
-
-```typescript
-import { Platform, StyleSheet } from 'react-native';
-
-// Platform-specific styling
-const styles = StyleSheet.create({
-  shadow: Platform.select({
-    ios: {
-      shadowColor: '#000',
-      shadowOffset: { width: 0, height: 2 },
-      shadowOpacity: 0.1,
-      shadowRadius: 4,
-    },
-    android: {
-      elevation: 4,
-    },
-    default: {},
-  })!,
-  container: {
-    paddingTop: Platform.OS === 'ios' ? 44 : 0,
-  },
-});
-
-// Platform-specific files (RN resolves automatically)
-// DatePicker.ios.tsx  — uses native iOS date picker
-// DatePicker.android.tsx — uses Android material date picker
-// DatePicker.tsx — fallback / web
-```
-
-## Anti-Patterns
-
-- **ScrollView for long lists**: `ScrollView` renders all children at once. Use `FlatList` or `SectionList` for lists with more than ~20 items.
-- **Inline styles and functions in render**: Creating new objects and functions on every render defeats `memo`. Extract to `StyleSheet.create` and `useCallback`.
-- **Ignoring Hermes**: Not enabling Hermes (or using an old RN version without it) wastes 30-50% startup performance.
-- **Untyped navigation**: Using `navigation.navigate('Screen')` without type definitions. Type your param lists for compile-time safety.
-
-## Integration Points
-
-- **Swift/Kotlin**: Native modules bridge platform APIs; see `swift-patterns.md` and `kotlin-patterns.md`.
-- **Testing**: See `mobile-testing.md` for Detox E2E and component testing strategies.
-- **React Patterns**: Core React hooks and component patterns apply; see `react-patterns.md` (typescript stack).
-- **State Management**: Use Zustand, Redux Toolkit, or React Query for state; principles from `react-patterns.md` apply.