# System Architecture & Invariants: Expo Router & React Native Mobile Specialist

## 1. System Overview
Modern React Native standards with Expo Router, the New Architecture (on by default), and safe area boundaries.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: Expo Router & React Native
- **Language Standard**: TypeScript
- **UI & Styling**: StyleSheet / NativeWind
- **Data Persistence**: SQLite / Supabase / REST
- **Engineering Philosophy**: modern

## 2. Core Architectural Invariants
- **Feature-Colocated Structure**: Group components, hooks, tests, and utils inside domain feature folders.
- **Guard Clauses & Early Returns**: Exit early from functions to eliminate deeply nested if-else pyramids.
- **Accessible UI by Default**: Enforce semantic HTML, keyboard navigability, and proper ARIA roles.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Minimal Surgical Diffs**: Touch only lines relevant to prompt. Preserve existing comments and formatting.
- **Preserve Codebase Idioms**: Match existing naming conventions, indentation, and directory patterns.

## 5. Domain-Specific Invariants
- Never perform heavy synchronous calculations during render passes.
- Do not import bare native modules that break Expo Go unless config plugins are configured.

## 6. Implementation Reference Patterns

### Preferred Pattern
```typescript
import { View, Text, StyleSheet } from "react-native";
import { Image } from "expo-image";
import { useSafeAreaInsets } from "react-native-safe-area-context";

export default function ProfileScreen() {
  const insets = useSafeAreaInsets();
  return (
    <View style={[styles.container, { paddingTop: insets.top, paddingBottom: insets.bottom }]}>
      <Image source={{ uri: "https://example.com/avatar.png" }} style={styles.avatar} contentFit="cover" />
      <Text style={styles.title}>User Profile</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: "#fff", paddingHorizontal: 16 },
  avatar: { width: 80, height: 80, borderRadius: 40 },
  title: { fontSize: 20, fontWeight: "600", marginTop: 12 },
});
```

### Forbidden Anti-Pattern
```typescript
export default function BadProfile({ navigation }: any) {
  return (
    <div style={{ marginTop: 50 }}>
      <img src="avatar.png" />
      <button onClick={() => navigation.navigate("Home")}>Go</button>
    </div>
  );
}
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Use Expo Router file-based routing under app/ directory; avoid legacy navigation container wrappers.
2. Guard all screen boundaries with react-native-safe-area-context insets.
3. Use expo-image for high-performance memory-cached image rendering.
4. Test styles on both iOS and Android platforms to prevent layout clipping and notch collisions.