normogen/docs/adr/monorepo-structure.md

Monorepo Structure

Repository Layout

normogen/                          # Root Forgejo repository
├── backend/                       # Rust backend (Axum + MongoDB)
│   ├── src/                       # Source code
│   │   ├── main.rs                # Entry point
│   │   ├── auth/                  # Authentication
│   │   │   ├── mod.rs
│   │   │   ├── jwt_service.rs
│   │   │   ├── claims.rs
│   │   │   └── middleware.rs
│   │   ├── api/                   # API endpoints
│   │   │   ├── mod.rs
│   │   │   ├── users.rs
│   │   │   ├── families.rs
│   │   │   ├── profiles.rs
│   │   │   ├── health_data.rs
│   │   │   ├── lab_results.rs
│   │   │   ├── medications.rs
│   │   │   ├── appointments.rs
│   │   │   └── shares.rs
│   │   ├── db/                    # Database
│   │   │   ├── mod.rs
│   │   │   ├── mongo.rs
│   │   │   ├── models.rs
│   │   │   └── repositories.rs
│   │   ├── config/                # Configuration
│   │   │   ├── mod.rs
│   │   │   ├── app.rs
│   │   │   ├── jwt.rs
│   │   │   ├── mongo.rs
│   │   │   └── cors.rs
│   │   ├── middleware/            # Middleware
│   │   │   ├── mod.rs
│   │   │   ├── auth.rs
│   │   │   ├── logging.rs
│   │   │   └── rate_limit.rs
│   │   ├── utils/                 # Utilities
│   │   │   ├── mod.rs
│   │   │   ├── crypto.rs
│   │   │   └── validation.rs
│   │   └── error.rs               # Error types
│   ├── docker/
│   │   ├── Dockerfile             # Production build
│   │   └── Dockerfile.dev         # Development build
│   ├── config/
│   │   ├── .env.example           # Environment template
│   │   └── defaults.env           # Default values
│   ├── k8s/                       # Kubernetes manifests (future)
│   │   ├── base/
│   │   └── overlays/
│   ├── Cargo.toml                 # Dependencies
│   ├── Cargo.lock                 # Lock file
│   ├── docker-compose.yml         # Production deployment
│   ├── docker-compose.dev.yml     # Development deployment
│   └── README.md                  # Backend README
│
├── mobile/                        # React Native (iOS + Android)
│   ├── src/                       # Source code
│   │   ├── components/            # Reusable components
│   │   │   ├── common/
│   │   │   ├── health/
│   │   │   ├── lab/
│   │   │   └── medication/
│   │   ├── screens/               # Screen components
│   │   │   ├── auth/
│   │   │   ├── home/
│   │   │   ├── family/
│   │   │   ├── profile/
│   │   │   ├── health/
│   │   │   ├── lab/
│   │   │   └── settings/
│   │   ├── navigation/            # Navigation config
│   │   │   ├── AppNavigator.tsx
│   │   │   ├── AuthNavigator.tsx
│   │   │   └── LinkingConfiguration.tsx
│   │   ├── store/                 # Redux store
│   │   │   ├── slices/
│   │   │   │   ├── authSlice.ts
│   │   │   │   ├── userSlice.ts
│   │   │   │   ├── familySlice.ts
│   │   │   │   ├── profileSlice.ts
│   │   │   │   └── healthDataSlice.ts
│   │   │   └── store.ts
│   │   ├── services/              # API services
│   │   │   ├── api.ts             # Axios client
│   │   │   ├── authService.ts
│   │   │   ├── userService.ts
│   │   │   └── healthDataService.ts
│   │   ├── utils/                 # Utilities
│   │   │   ├── encryption.ts      # Client-side encryption
│   │   │   ├── validation.ts
│   │   │   └── constants.ts
│   │   ├── hooks/                 # Custom hooks
│   │   │   ├── useAuth.ts
│   │   │   └── useEncryptedStorage.ts
│   │   ├── types/                 # TypeScript types
│   │   │   └── index.ts
│   │   └── assets/                # Images, fonts
│   ├── android/                   # Android native code
│   │   ├── app/
│   │   └── build.gradle
│   ├── ios/                       # iOS native code
│   │   ├── Normogen
│   │   └── Podfile
│   ├── package.json
│   ├── tsconfig.json
│   ├── App.tsx                    # Entry component
│   ├── README.md
│   └── .env.example
│
├── web/                           # React web app
│   ├── src/                       # Source code
│   │   ├── components/            # Reusable components
│   │   │   ├── common/
│   │   │   ├── health/
│   │   │   ├── lab/
│   │   │   └── charts/
│   │   ├── pages/                 # Page components
│   │   │   ├── auth/
│   │   │   ├── home/
│   │   │   ├── family/
│   │   │   ├── profile/
│   │   │   ├── health/
│   │   │   ├── lab/
│   │   │   └── settings/
│   │   ├── store/                 # Redux store (shared with mobile)
│   │   │   ├── slices/
│   │   │   └── store.ts
│   │   ├── services/              # API services (shared with mobile)
│   │   │   ├── api.ts
│   │   │   └── ...
│   │   ├── utils/                 # Utilities (shared with mobile)
│   │   │   ├── encryption.ts
│   │   │   └── ...
│   │   ├── hooks/                 # Custom hooks
│   │   │   └── ...
│   │   ├── types/                 # TypeScript types (shared)
│   │   │   └── index.ts
│   │   ├── styles/                # CSS/global styles
│   │   │   └── global.css
│   │   └── App.tsx
│   ├── package.json
│   ├── tsconfig.json
│   ├── index.html
│   ├── vite.config.ts             # Vite config
│   └── README.md
│
├── shared/                        # Shared TypeScript code
│   ├── src/
│   │   ├── types/                 # Shared type definitions
│   │   │   ├── user.ts
│   │   │   ├── family.ts
│   │   │   ├── profile.ts
│   │   │   ├── healthData.ts
│   │   │   ├── labResults.ts
│   │   │   ├── medications.ts
│   │   │   ├── appointments.ts
│   │   │   ├── shares.ts
│   │   │   └── api.ts
│   │   ├── validation/            # Zod schemas
│   │   │   ├── user.ts
│   │   │   ├── family.ts
│   │   │   └── healthData.ts
│   │   ├── encryption/            # Encryption utilities
│   │   │   ├── crypto.ts
│   │   │   └── keyDerivation.ts
│   │   ├── api/                   # Shared API client
│   │   │   ├── client.ts
│   │   │   └── endpoints.ts
│   │   └── constants/             # Shared constants
│   │       ├── routes.ts
│   │       └── config.ts
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
│
├── thoughts/                      # Research & design docs
│   ├── research/
│   │   ├── 2026-02-14-rust-framework-comparison.md
│   │   ├── 2026-02-14-rust-framework-performance-research.md
│   │   ├── 2026-02-14-performance-findings.md
│   │   ├── 2026-02-14-research-summary.md
│   │   ├── 2026-02-14-frontend-mobile-research.md
│   │   ├── 2026-02-14-frontend-decision-summary.md
│   │   ├── 2026-02-14-state-management-research.md
│   │   ├── 2026-02-14-state-management-decision.md
│   │   ├── 2026-02-14-jwt-authentication-research.md
│   │   ├── 2026-02-14-jwt-authentication-decision.md
│   │   ├── 2026-02-14-mongodb-schema-design-research.md
│   │   ├── 2026-02-14-mongodb-schema-decision.md
│   │   ├── 2026-02-14-backend-deployment-constraints.md
│   │   └── 2026-02-14-monorepo-structure.md
│   └── research/
│
├── .gitignore                     # Root gitignore
├── README.md                      # Root README
├── docker-compose.root.yml        # Run all services (optional)
└── .forgejo/                      # Forgejo CI/CD workflows
    └── workflows/
        ├── backend-build.yml
        ├── mobile-build.yml
        └── web-build.yml

Directory Creation Commands

# Create root directories
mkdir -p backend/{src/{auth,api,db,config,middleware,utils},docker,config,k8s/base,k8s/overlays/homelab,k8s/overlays/production}
mkdir -p mobile/{src/{components/{common,health,lab,medication},screens/{auth,home,family,profile,health,lab,settings},navigation,store/slices,services,utils,hooks,types,assets},android,ios}
mkdir -p web/{src/{components/{common,health,lab,charts},pages/{auth,home,family,profile,health,lab,settings},store/slices,services,utils,hooks,types,styles}}
mkdir -p shared/src/{types,validation,encryption,api,constants}
mkdir -p thoughts/research
mkdir -p .forgejo/workflows

# Create placeholder files
touch backend/src/{main.rs,auth/mod.rs,api/mod.rs,db/mod.rs,config/mod.rs,middleware/mod.rs,utils/mod.rs,error.rs}
touch mobile/src/{App.tsx,navigation/AppNavigator.tsx,store/store.ts,services/api.ts,utils/encryption.ts}
touch web/src/{App.tsx,store/store.ts,services/api.ts,utils/encryption.ts}
touch shared/src/{types/index.ts,validation/index.ts,encryption/crypto.ts,api/client.ts}

Git Strategy

Branch Strategy

• main: Production releases
• develop: Development integration
• feature/backend-*: Backend features
• feature/mobile-*: Mobile features
• feature/web-*: Web features
• feature/shared-*: Shared code features

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, style, refactor, test, chore

Scopes: backend, mobile, web, shared, ci/cd

Examples:

• feat(backend): Implement JWT authentication with refresh tokens
• fix(mobile): Resolve encryption key storage issue
• docs(shared): Update API type definitions
• chore(ci/cd): Add Forgejo workflow for backend builds

Shared Code Management

TypeScript Package

The shared/ directory contains TypeScript code shared between mobile and web:

• Type definitions (API models)
• Validation schemas (Zod)
• Encryption utilities
• API client
• Constants

Usage in Mobile/Web

// mobile/package.json and web/package.json
{
  "dependencies": {
    "shared": "file:../shared"
  }
}

Watch Mode for Development

# In shared/ directory
npm run watch  # Watch and rebuild on changes

# In mobile/ and web/ directories
# Changes to shared/ are automatically picked up

Next Steps

1. Initialize Monorepo Structure

   • Create all directories
   • Create placeholder files
   • Update root .gitignore

2. Backend Initialization

   • Initialize Rust project (backend/)
   • Setup Cargo.toml
   • Create docker-compose files
   • Create Dockerfiles

3. Shared Code Setup

   • Initialize TypeScript project (shared/)
   • Setup type definitions
   • Setup Zod validation schemas
   • Setup encryption utilities

4. Mobile Setup (Phase 3)

   • Initialize React Native project
   • Setup Redux Toolkit
   • Setup navigation

5. Web Setup (Phase 3)

   • Initialize React project
   • Setup Redux Toolkit
   • Setup routing