@mr.dj2u/knowledge 0.1.0

package/dist/content/patterns/routing/file-based-routing.md

@@ -0,0 +1,186 @@
+# File-Based Routing with Expo Router
+
+## Description
+
+File-based routing in Expo Router automatically generates routes from the file structure under the `app/` directory. This pattern eliminates manual route configuration and makes navigation structure immediately visible from the filesystem. Routes are only defined under `app/` — components are NOT split into separate `src/screens/` folders, preventing the duplication problem.
+
+## When to Use
+
+**Always use** file-based routing for all Expo Router applications:
+- ✅ All page-level components live under `app/` directory structure
+- ✅ Route hierarchy directly mirrors file structure
+- ✅ Route organization is enforced by filesystem constraints
+- ✅ Single source of truth for application navigation
+
+## Code Example
+
+### File Structure Maps to Routes
+
+```
+app/
+├── _layout.tsx              → Root layout wrapper (providers, fonts, styling)
+├── index.tsx                → / (home page)
+├── about.tsx                → /about
+├── (drawer)/                → Route group (no URL segment)
+│   ├── _layout.tsx          → Drawer navigator wrapper
+│   ├── home.tsx             → /home
+│   └── profile.tsx          → /profile
+├── (auth)/                  → Route group for authentication
+│   ├── sign-in.tsx          → /sign-in
+│   └── sign-up.tsx          → /sign-up
+├── events/
+│   ├── index.tsx            → /events (list)
+│   └── [id].tsx             → /events/:id (detail)
+└── guides/
+    ├── PLZA/
+    │   ├── index.tsx        → /guides/PLZA
+    │   └── strategies/
+    │       └── [id].tsx     → /guides/PLZA/strategies/:id
+```
+
+**From:** PokePages, not-hot-dog, DJsPortfolio (reference Expo app src/app folders)
+
+### Root Layout Setup
+
+```typescript
+// app/_layout.tsx
+import { Stack } from 'expo-router';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { Provider } from 'zustand';
+import { useAuthStore } from '@/store/authStore';
+
+export default function RootLayout() {
+  const { isLoading } = useAuthStore();
+
+  if (isLoading) {
+    return <LoadingScreen />;
+  }
+
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <Stack screenOptions={{ headerShown: false }}>
+        <Stack.Screen name="(drawer)" />
+        <Stack.Screen name="(auth)" />
+      </Stack>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+**Pattern from:** core-monorepo/apps/*/src/app/_layout.tsx, PokePages/src/app/_layout.tsx
+
+## Configuration
+
+### Setup in `app.json`
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-router",
+        {
+          "origin": false,
+          "asyncRoutes": "development",
+          "apiRoutes": true
+        }
+      ]
+    ],
+    "experiments": {
+      "typedRoutes": true
+    }
+  }
+}
+```
+
+### TypeScript Configuration
+
+Enable typed routes in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "references": [{ "path": "./tsconfig.app.json" }]
+}
+```
+
+## Best Practices
+
+### ✅ DO
+
+1. **Keep `app/` files lean** — only routing and layout logic
+   ```typescript
+   // app/events/[id].tsx ✅ GOOD
+   import { EventDetail } from '@/components/EventDetail';
+   import { useLocalSearchParams } from 'expo-router';
+   
+   export default function EventDetailRoute() {
+     const { id } = useLocalSearchParams<{ id: string }>();
+     return <EventDetail eventId={id} />;
+   }
+   ```
+
+2. **Use route groups** for organizational structure without affecting URLs
+   ```
+   (drawer)/        ← drawer navigation group, no URL
+   ├── (tabs)/      ← tabs group nested in drawer, no URL
+   │   ├── home.tsx → /home
+   │   └── profile.tsx → /profile
+   ```
+
+3. **Import components from `src/components/`** or `src/screens/`
+   ```typescript
+   import { ProfileScreen } from '@/components/ProfileScreen';
+   // NOT: import { ProfileScreen } from './ProfileScreen';
+   ```
+
+4. **Use platform-specific files** for route variations
+   ```
+   [id].tsx         ← default (all platforms)
+   [id].web.tsx     ← web-specific
+   [id].native.tsx  ← iOS/Android specific
+   ```
+
+### ❌ DON'T
+
+1. **Don't put complex logic in route files**
+   ```typescript
+   // ❌ BAD
+   export default function EventRoute() {
+     const [events, setEvents] = useState([]);
+     const [loading, setLoading] = useState(false);
+     // ... 50+ lines of business logic
+     return <View>...</View>;
+   }
+   ```
+
+2. **Don't duplicate screens in `src/screens/`** AND reference from `app/`
+   ```
+   ❌ app/events.tsx AND src/screens/EventsScreen.tsx
+   ✅ app/events.tsx imports from @/components/EventsScreen
+   ```
+
+3. **Don't use `require()` for dynamic routing** — let Expo Router handle it
+   ```typescript
+   // ❌ BAD
+   const Screen = require(`./screens/${routeName}`);
+   
+   // ✅ GOOD
+   router.push(`/events/${eventId}`);
+   ```
+
+## Related Patterns
+
+- [Dynamic Routes](./dynamic-routes.md) — Using `[param].tsx` syntax
+- [Route Groups](./route-groups.md) — Organizing routes with `(group)/` syntax
+- [Navigation Patterns](./navigation-patterns.md) — router.push, Link components, deep linking
+- [API Routes](./api-routes.md) — `+api.ts` catch-all pattern for server endpoints
+
+---
+
+*Pattern extracted from production repositories: PokePages, not-hot-dog, DJsPortfolio, core-monorepo*
+*File structure observed in: reference Expo app src/app folders

package/dist/content/patterns/routing/route-groups.md

@@ -0,0 +1,429 @@
+# Route Groups Pattern
+
+## Description
+
+Route groups use parentheses `(groupName)` to organize routes without adding URL segments. Groups enable shared layouts, nested navigation stacks, and logical route organization within Expo Router's file-based routing system.
+
+## When to Use
+
+**Use route groups** for:
+- ✅ Shared layout wrapping multiple routes without URL changes
+- ✅ Tab navigation stacks (e.g., `(tabs)/home`, `(tabs)/explore`)
+- ✅ Authentication flow separation (`(auth)` vs main app)
+- ✅ Nested drawer navigation within groups
+- ✅ Organizing related features without URL hierarchy
+
+## Code Example
+
+### Basic Route Group with Shared Layout
+
+```typescript
+// File: src/app/(drawer)/_layout.tsx
+import { Drawer } from 'expo-router/drawer';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+export default function DrawerLayout() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <Drawer
+        screenOptions={{
+          headerShown: true,
+          drawerType: 'slide',
+        }}
+      >
+        <Drawer.Screen
+          name="(tabs)"
+          options={{
+            title: 'Home',
+            drawerIcon: ({ color }) => <HomeIcon color={color} />,
+          }}
+        />
+        <Drawer.Screen
+          name="settings"
+          options={{
+            title: 'Settings',
+            drawerIcon: ({ color }) => <SettingsIcon color={color} />,
+          }}
+        />
+      </Drawer>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+```typescript
+// File: src/app/(drawer)/(tabs)/_layout.tsx
+import { Tabs } from 'expo-router';
+import { HomeIcon, ExploreIcon, ProfileIcon } from '@/components/Icons';
+
+export default function TabLayout() {
+  return (
+    <Tabs
+      screenOptions={{
+        headerShown: false,
+        tabBarActiveTintColor: '#007AFF',
+      }}
+    >
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: 'Home',
+          tabBarIcon: ({ color }) => <HomeIcon color={color} />,
+        }}
+      />
+      <Tabs.Screen
+        name="explore"
+        options={{
+          title: 'Explore',
+          tabBarIcon: ({ color }) => <ExploreIcon color={color} />,
+        }}
+      />
+      <Tabs.Screen
+        name="profile"
+        options={{
+          title: 'Profile',
+          tabBarIcon: ({ color }) => <ProfileIcon color={color} />,
+        }}
+      />
+    </Tabs>
+  );
+}
+```
+
+```typescript
+// File: src/app/(drawer)/(tabs)/index.tsx
+import { View, Text } from 'react-native';
+
+export default function HomeScreen() {
+  return (
+    <View className="flex-1 items-center justify-center">
+      <Text>Home Tab</Text>
+    </View>
+  );
+}
+// Route: /home (no "(tabs)" in URL)
+```
+
+### Multiple Nested Groups
+
+```
+src/app/
+├── _layout.tsx                  (root: Stack)
+├── (drawer)/                    (drawer group, no URL)
+│   ├── _layout.tsx              (Drawer layout)
+│   ├── (tabs)/                  (tabs group within drawer, no URL)
+│   │   ├── _layout.tsx          (Tabs layout)
+│   │   ├── index.tsx            → /
+│   │   ├── explore.tsx          → /explore
+│   │   └── profile.tsx          → /profile
+│   └── settings.tsx             → /settings
+├── (auth)/                      (auth group, no URL)
+│   ├── _layout.tsx              (Stack layout for auth flow)
+│   ├── sign-in.tsx              → /sign-in
+│   └── sign-up.tsx              → /sign-up
+└── +not-found.tsx               (catch-all 404)
+
+// Key insight: Route groups "(drawer)" and "(tabs)" don't appear in URLs
+// Routes map: / (home), /explore, /profile, /settings, /sign-in, /sign-up
+```
+
+### Authentication Flow with Route Groups
+
+```typescript
+// File: src/app/_layout.tsx (Root Layout)
+import { Stack } from 'expo-router';
+import { useAuthStore } from '@/store/authStore';
+
+export default function RootLayout() {
+  const { isLoggedIn, loading } = useAuthStore();
+
+  if (loading) {
+    return <LoadingScreen />;
+  }
+
+  return (
+    <Stack
+      screenOptions={{
+        headerShown: false,
+        animationEnabled: true,
+      }}
+    >
+      {isLoggedIn ? (
+        // Main app routes (drawer + tabs)
+        <Stack.Screen name="(drawer)" />
+      ) : (
+        // Auth routes (sign-in, sign-up)
+        <Stack.Screen
+          name="(auth)"
+          options={{
+            animationEnabled: false,
+          }}
+        />
+      )}
+    </Stack>
+  );
+}
+```
+
+```typescript
+// File: src/app/(auth)/_layout.tsx
+import { Stack } from 'expo-router';
+
+export default function AuthLayout() {
+  return (
+    <Stack
+      screenOptions={{
+        headerShown: false,
+        animationEnabled: true,
+      }}
+    >
+      <Stack.Screen name="sign-in" />
+      <Stack.Screen name="sign-up" />
+    </Stack>
+  );
+}
+```
+
+```typescript
+// File: src/app/(auth)/sign-in.tsx
+import { View, Text, Pressable } from 'react-native';
+import { router } from 'expo-router';
+
+export default function SignInScreen() {
+  const handleSignIn = async () => {
+    // Authentication logic
+    await authenticate();
+    // Replace entire stack with main app
+    router.replace('/(drawer)/(tabs)/');
+  };
+
+  return (
+    <View className="flex-1 justify-center items-center">
+      <Text>Sign In</Text>
+      <Pressable onPress={handleSignIn}>
+        <Text>Login</Text>
+      </Pressable>
+    </View>
+  );
+}
+// Route: /sign-in (not /(auth)/sign-in)
+```
+
+### Feature-Specific Groups
+
+```
+src/app/
+├── (drawer)/
+│   ├── _layout.tsx
+│   ├── (tabs)/
+│   │   ├── _layout.tsx
+│   │   ├── index.tsx
+│   │   └── explore.tsx
+│   └── (guides)/            (guides feature group)
+│       ├── _layout.tsx      (guides layout/header)
+│       ├── index.tsx        → /guides
+│       ├── [id].tsx         → /guides/[id]
+│       └── search.tsx       → /guides/search
+└── (modal)/                 (modal overlay group)
+    ├── _layout.tsx          (modal presentation)
+    ├── settings-modal.tsx   → /settings-modal
+    └── share-modal.tsx      → /share-modal
+
+// Routes: /guides, /guides/123, /guides/search, /settings-modal, /share-modal
+```
+
+```typescript
+// File: src/app/(drawer)/(guides)/_layout.tsx
+import { Stack } from 'expo-router';
+
+export default function GuidesLayout() {
+  return (
+    <Stack
+      screenOptions={{
+        headerShown: true,
+        headerTitle: 'Guides',
+        headerBackVisible: true,
+      }}
+    >
+      <Stack.Screen name="index" />
+      <Stack.Screen name="[id]" />
+      <Stack.Screen name="search" />
+    </Stack>
+  );
+}
+```
+
+### Modal Presentation with Route Groups
+
+```typescript
+// File: src/app/_layout.tsx
+import { Stack } from 'expo-router';
+
+export default function RootLayout() {
+  return (
+    <Stack>
+      {/* Main app */}
+      <Stack.Screen name="(drawer)" />
+
+      {/* Modal stack (presented on top) */}
+      <Stack.Screen
+        name="(modal)"
+        options={{
+          presentation: 'modal',
+          headerShown: false,
+          animationEnabled: true,
+        }}
+      />
+    </Stack>
+  );
+}
+```
+
+```typescript
+// File: src/app/(modal)/_layout.tsx
+import { Stack } from 'expo-router';
+
+export default function ModalLayout() {
+  return (
+    <Stack
+      screenOptions={{
+        presentation: 'modal',
+      }}
+    >
+      <Stack.Screen name="settings-modal" />
+      <Stack.Screen name="share-modal" />
+    </Stack>
+  );
+}
+```
+
+```typescript
+// File: src/app/(modal)/settings-modal.tsx
+import { View, Text, Pressable } from 'react-native';
+import { router } from 'expo-router';
+
+export default function SettingsModal() {
+  return (
+    <View className="flex-1 bg-white rounded-t-2xl p-4">
+      <View className="flex-row justify-between items-center mb-4">
+        <Text className="text-xl font-bold">Settings</Text>
+        <Pressable onPress={() => router.back()}>
+          <Text className="text-lg">✕</Text>
+        </Pressable>
+      </View>
+
+      {/* Settings content */}
+    </View>
+  );
+}
+// Route: /settings-modal (presented as modal)
+// Navigate: router.push('/settings-modal')
+```
+
+## Route Group Naming Conventions
+
+| Pattern | Purpose | URL Impact |
+|---------|---------|-----------|
+| `(tabs)` | Tab navigation group | No URL segment |
+| `(drawer)` | Drawer navigation group | No URL segment |
+| `(auth)` | Authentication flow | No URL segment |
+| `(modal)` | Modal overlays | No URL segment |
+| `(feature-name)` | Feature-specific routes | No URL segment |
+
+## Navigation Patterns
+
+### Navigate Between Groups
+
+```typescript
+import { router } from 'expo-router';
+
+// Navigate to route in different group
+router.push('/'); // Home in (tabs)
+router.push('/guides'); // Guides in (guides)
+router.push('/settings-modal'); // Modal in (modal)
+
+// Navigate with params
+router.push('/guides/123');
+router.push({
+  pathname: '/guides/[id]',
+  params: { id: '123' },
+});
+
+// Replace (clear stack)
+router.replace('/(drawer)/(tabs)/');
+router.replace('/(auth)/sign-in');
+```
+
+## Best Practices
+
+### ✅ DO
+
+1. **Use groups to organize related routes**
+   ```
+   (drawer)/         - Main app navigation
+   (tabs)/          - Tab routes
+   (auth)/          - Auth flow
+   (guides)/        - Feature routes
+   ```
+
+2. **Keep _layout.tsx files focused** on navigation setup
+   ```typescript
+   export default function GuideLayout() {
+     return (
+       <Stack screenOptions={{ /* navigation options */ }}>
+         <Stack.Screen name="index" />
+         <Stack.Screen name="[id]" />
+       </Stack>
+     );
+   }
+   ```
+
+3. **Use router.replace()** when changing auth states
+   ```typescript
+   // After login, replace auth stack with main app
+   router.replace('/(drawer)/(tabs)/');
+   
+   // After logout, replace main app with auth
+   router.replace('/(auth)/sign-in');
+   ```
+
+### ❌ DON'T
+
+1. **Don't nest groups excessively**
+   ```typescript
+   // ❌ TOO DEEP
+   (app)/(main)/(features)/(guides)/index.tsx
+   
+   // ✅ REASONABLE
+   (drawer)/(guides)/index.tsx
+   ```
+
+2. **Don't duplicate layout logic**
+   ```typescript
+   // ❌ DUPLICATED
+   // (drawer)/_layout.tsx - defines Drawer
+   // (drawer)/(tabs)/_layout.tsx - defines Drawer again
+   
+   // ✅ COMPOSED
+   // (drawer)/_layout.tsx - wraps (tabs) group
+   // (drawer)/(tabs)/_layout.tsx - defines Tabs within drawer
+   ```
+
+3. **Don't forget router.replace()** for auth transitions
+   ```typescript
+   // ❌ LEAVES BACK BUTTON
+   router.push('/(drawer)/(tabs)/');
+   
+   // ✅ CLEAR STACK
+   router.replace('/(drawer)/(tabs)/');
+   ```
+
+## Related Patterns
+
+- [File-Based Routing](./file-based-routing.md) — Routing fundamentals
+- [Dynamic Routes](./dynamic-routes.md) — Dynamic segments
+
+---
+
+*Pattern extracted from production repositories: core-monorepo, PokePages, DJsPortfolio*
+*Files: src/app/ directory structures from Expo Router projects*