# Project Structure

Overview of the OrchardGo project organization.

## Root Directory

```
orchardgo/
├── android/           # Android native code
├── ios/              # iOS native code
├── src/              # JavaScript/TypeScript source
├── brands/           # Brand-specific assets and config
├── docs/             # Documentation
├── scripts/          # Build and deployment scripts
├── static/           # Static assets
├── __tests__/        # Test files
├── .env.shadow       # Environment template
├── package.json      # Dependencies and scripts
└── README.md         # Project overview
```

## Source Directory (`src/`)

```
src/
├── components/       # Reusable UI components
├── screens/          # Screen components
├── navigation/       # Navigation configuration
├── hooks/            # Custom React hooks
├── state/            # Global state (Apollo reactive vars, Redux)
├── queries/          # GraphQL queries and mutations
├── branding/         # Brand configuration logic
├── utils/            # Utility functions
├── config.js         # App configuration
├── apollo/           # Apollo Client setup
├── services/         # External services integration
└── types/            # TypeScript type definitions
```

### Components (`src/components/`)

Reusable UI components organized by feature:

```
components/
├── Button/
│   ├── Button.tsx
│   ├── Button.test.tsx
│   └── Button.styles.ts
├── Card/
├── Input/
└── ...
```

**Guidelines:**
- One component per directory
- Include tests alongside component
- Export from index file for clean imports

### Screens (`src/screens/`)

Full-screen views organized by feature:

```
screens/
├── HomeScreen/
│   ├── HomeScreen.tsx
│   ├── HomeScreen.test.tsx
│   └── components/      # Screen-specific components
│       └── HeaderCard.tsx
├── ProfileScreen/
└── ...
```

**Guidelines:**
- One screen per directory
- Screen-specific components in nested `components/` dir
- Keep screens focused, extract complex logic to hooks

### Navigation (`src/navigation/`)

```
navigation/
├── RootNavigator.tsx     # Main navigator
├── RootSwitchNavigator.tsx  # Auth flow switch
├── MainStack.tsx         # Authenticated screens
├── AuthStack.tsx         # Unauthenticated screens
└── types.ts              # Navigation types
```

### Hooks (`src/hooks/`)

Custom React hooks organized by domain:

```
hooks/
├── auth/
│   ├── useLogin.ts
│   ├── useLogout.ts
│   └── utils/
│       └── initializeSession.js
├── queries/
│   ├── useUser.ts
│   └── useProfile.ts
└── ui/
    ├── useTheme.ts
    └── useResponsive.ts
```

**Guidelines:**
- Prefix with `use`
- Group related hooks
- Include utility functions in `utils/` subdirectories

### State Management (`src/state/`)

Global state using Apollo reactive variables and Redux:

```
state/
├── session.ts           # Session state
├── ui.ts                # UI state (modals, overlays)
├── store.ts             # Redux store setup
├── reducers/
└── sagas/
```

### GraphQL (`src/queries/`)

```
queries/
├── user/
│   ├── queries.ts
│   ├── mutations.ts
│   └── fragments.ts
├── profile/
├── constants.ts         # GraphQL constants
└── types.ts             # Generated types
```

**Guidelines:**
- Organize by domain/feature
- Use fragments for reusability
- Generate types from schema

### Branding (`src/branding/`)

```
branding/
├── index.ts             # Brand exports
├── types.ts             # Brand types
├── config.ts            # Brand configuration loader
└── hooks/
    └── useBrand.ts
```

## Platform-Specific Code

### iOS (`ios/`)

```
ios/
├── orchardgo/
│   ├── AppDelegate.mm
│   ├── Info.plist
│   └── Images.xcassets/
├── orchardgo.xcworkspace/
├── Podfile              # CocoaPods dependencies
└── Podfile.lock         # Locked pod versions
```

### Android (`android/`)

```
android/
├── app/
│   ├── src/
│   │   └── main/
│   │       ├── java/
│   │       ├── res/
│   │       └── AndroidManifest.xml
│   └── build.gradle     # App-level Gradle
├── build.gradle         # Project-level Gradle
└── gradle.properties    # Gradle properties
```

## Brand Assets (`brands/`)

```
brands/
├── orchard/
│   ├── config.json
│   ├── icons/
│   ├── images/
│   ├── android/
│   │   └── google-services/
│   └── ios/
│       └── GoogleService-Info/
└── awal/
    └── (same structure)
```

See [Branding Guide](../guides/branding.md) for details.

## Scripts (`scripts/`)

Build, deployment, and utility scripts:

```
scripts/
├── clean.sh             # Clean build artifacts
├── setup.sh             # Setup project
├── start.sh             # Start app
├── deployJs.sh          # Deploy to CodePush
├── deployBinary.sh      # Deploy to stores
└── ...
```

## Static Assets (`static/`)

Static files served for deep links:

```
static/
├── insights.theorchard.com/
│   └── .well-known/
│       ├── apple-app-site-association
│       └── assetlinks.json
└── (other domains)
```

## Configuration Files

### Root-Level Config

- `.env` - Environment variables (gitignored)
- `.env.shadow` - Environment template
- `package.json` - Dependencies and scripts
- `tsconfig.json` - TypeScript configuration
- `jest.config.js` - Jest test configuration
- `.eslintrc.js` - ESLint rules
- `.prettierrc` - Prettier formatting
- `babel.config.js` - Babel configuration

### Version Files

- `.node-version` - Node.js version
- `.ruby-version` - Ruby version
- `.java-version` - Java version
- `.xcode-version` - Xcode version
- `.yarn-version` - Yarn version

## Import Aliases

TypeScript/Babel configured with path aliases:

```typescript
import { Button } from '@/components';
import { useAuth } from '@/hooks/auth';
import { sessionVar } from '@/state/session';
import { GET_USER } from '@/queries/user';
```

**Common aliases:**
- `@/` → `src/`
- `@components` → `src/components`
- `@screens` → `src/screens`
- `@hooks` → `src/hooks`
- `@utils` → `src/utils`

## File Naming Conventions

### Components
- PascalCase: `Button.tsx`, `UserCard.tsx`
- Tests: `Button.test.tsx`
- Styles: `Button.styles.ts`

### Hooks
- camelCase with `use` prefix: `useAuth.ts`, `useProfile.ts`

### Utilities
- camelCase: `formatDate.ts`, `parseUrl.ts`

### Constants
- camelCase file: `constants.ts`
- SCREAMING_SNAKE_CASE exports: `API_URL`, `MAX_RETRY_COUNT`

### Types
- PascalCase: `User.ts`, `Profile.ts`
- Or colocated: `user.types.ts`

## Code Organization Principles

### 1. Feature-Based Organization

Group by feature, not by file type:

```
✅ Good:
features/
└── profile/
    ├── ProfileScreen.tsx
    ├── ProfileCard.tsx
    ├── useProfile.ts
    └── profile.types.ts

❌ Bad:
screens/ProfileScreen.tsx
components/ProfileCard.tsx
hooks/useProfile.ts
types/profile.types.ts
```

### 2. Colocate Related Files

Keep related files together:
- Component with its test
- Component with its styles
- Feature with its types

### 3. Single Responsibility

Each file should have a single, clear purpose:
- One component per file
- One hook per file
- Utility functions grouped by domain

### 4. Explicit Exports

Use index files for clean exports:

```typescript
// components/Button/index.ts
export { Button } from './Button';
export type { ButtonProps } from './Button.types';
```

## Testing Structure

Tests colocated with source:

```
src/
└── components/
    └── Button/
        ├── Button.tsx
        └── Button.test.tsx
```

Test utilities in `__tests__/`:

```
__tests__/
├── utils/
│   ├── mockData.ts
│   └── testHelpers.ts
└── setup.ts
```

## Next Steps

- [Naming Conventions](./naming-conventions.md)
- [Code Standards](./code-standards.md)
- [Architecture Decisions](./architecture-decisions.md)