# Repository Structure

**Status**: Planning - Some repos created, structure being defined

## Overview

Zelara uses a **modular git submodule architecture** where:
- `core` repo = anchor with shared systems
- Feature modules = separate repos as submodules
- Platform apps = separate repos as submodules
- Each repo can have its own wiki as submodule

## Current Structure

```
zelara-ai/core                          (this repo)
├── org/                                (submodule → zelara-ai/.github)
│   └── wikis/                          (submodule → zelara-ai/.github.wiki)
├── wikis/                              (submodule → zelara-ai/core.wiki)
└── README.md                           (vision-only, no technical details)
```

## Planned Structure

```
zelara-ai/core                          (anchor repo)
├── src/
│   └── packages/                       (shared TypeScript packages)
│       ├── shared/                     (@zelara/shared — types, constants)
│       ├── skill-tree/                 (@zelara/skill-tree — progression, unlock logic)
│       ├── state/                      (@zelara/state — local-first user data, StorageAdapter)
│       ├── device-linking/             (@zelara/device-linking — pairing, task offloading)
│       └── finance/                    (@zelara/finance — types, engines, repo interface)
├── modules/                            (feature modules as submodules)
│   ├── finance/                        (submodule → zelara-ai/module-finance)
│   │   ├── wikis/                      (submodule → zelara-ai/module-finance.wiki)
│   │   └── README.md                   (finance module vision)
│   ├── productivity/                   (submodule → zelara-ai/module-productivity)
│   │   ├── wikis/                      (submodule → zelara-ai/module-productivity.wiki)
│   │   └── README.md                   (productivity module vision)
│   └── green/                          (submodule → zelara-ai/module-green)
│       ├── wikis/                      (submodule → zelara-ai/module-green.wiki)
│       └── README.md                   (green module vision)
├── apps/                               (platform apps as submodules)
│   ├── desktop/                        (submodule → zelara-ai/app-desktop) — Zelara Core
│   │   ├── wikis/                      (submodule → zelara-ai/app-desktop.wiki)
│   │   └── README.md                   (desktop app overview)
│   ├── mobile/                         (submodule → zelara-ai/app-mobile) — Zelara (ai.zelara.mobile)
│   │   ├── wikis/                      (submodule → zelara-ai/app-mobile.wiki)
│   │   └── README.md                   (mobile app overview)
│   ├── finance-mobile/                 (submodule → zelara-ai/finance-mobile) — Zelara Finance (ai.zelara.finance) ✅ v0.6.0
│   │   └── README.md                   (finance app overview)
│   ├── testing-mobile/                 (submodule → zelara-ai/testing-mobile) — Zelara Testing (ai.zelara.testing) ✅ v0.6.0
│   │   └── README.md                   (testing app overview)
│   └── web/                            (submodule → zelara-ai/app-web) — deferred to v2
│       ├── wikis/                      (submodule → zelara-ai/app-web.wiki)
│       └── README.md                   (web app overview)
├── org/                                (submodule → zelara-ai/.github)
│   └── wikis/                          (submodule → zelara-ai/.github.wiki)
├── wikis/                              (submodule → zelara-ai/core.wiki)
├── README.md                           (vision-only, points to wiki for technical)
└── CLAUDE.md                           (minimal AI guidelines, points to wiki for details)
```

## Repository Purposes

### Core Repositories

**`zelara-ai/core`**
- Anchor repo that ties everything together
- Shared systems: skill tree, state management, device linking, build orchestration
- Root READMEs (vision-only, no technical details)
- Git submodules for modules, apps, wikis

**`zelara-ai/core.wiki`**
- Technical documentation for core
- Architecture decisions, planning, open questions
- Development workflow

### Feature Module Repositories

**`zelara-ai/module-finance`** + `.wiki`
- Personal/business finance organization
- Budget tracking, expense categorization
- Tax preparation automation
- Donation suggestions (portion of excess to green initiatives)

**`zelara-ai/module-productivity`** + `.wiki`
- Focus timers, calendar/email AI
- Task management, workflow automation
- Themed skins/accessories marketplace (profits to green causes)

**`zelara-ai/module-green`** + `.wiki`
- **Starter features**: Recycling tasks (paper bag usage, image validation)
- **Homeowner tools**: Carbon footprint calculations, reduction pathways
- Property-specific (city/suburbs/farm) recommendations
- Solar research, insulation, transportation alternatives

### Platform App Repositories

**`zelara-ai/app-desktop`** + `.wiki`
- Desktop app (Windows/Mac/Linux)
- Highest compute capability (runs full CV models, complex calculations)
- Acts as processing hub for linked mobile/web devices

**`zelara-ai/app-mobile`** + `.wiki`
- Mobile app (iOS/Android)
- Primary user interface for daily tasks
- Offloads heavy processing to linked Desktop
- Camera integration for image validation

**`zelara-ai/app-web`** + `.wiki`
- Web app (browser-based)
- Lowest compute capability
- Optional platform for users without Desktop/Mobile

### Organization Repositories

**`zelara-ai/.github`** + `.wiki`
- Organization profile, CODE_OF_CONDUCT, templates
- Org-level documentation

## README Philosophy

**Root READMEs** (in all repos):
- **Vision-only** - What the project does, why it exists
- **No technical details** - No architecture, no build instructions, no implementation plans
- **No "Getting Started"** - No setup guides (those live in wikis)
- **Point to wiki** - For technical details, architecture, development workflow

**Example**: `module-finance/README.md` should say "Finance module for Zelara. Helps organize personal/business finances. See [wiki](link) for technical details."

## Wiki Philosophy

**Wikis** (separate repos as submodules):
- **All technical content** - Architecture, design decisions, API docs
- **Planning documents** - Open questions, decision logs
- **Development workflow** - How to build, test, contribute
- **Detailed specs** - Feature requirements, implementation details

**Home.md** = Navigation to other wiki pages

## Module Nesting

Modules can have their own submodules for nested features:

```
modules/green/                          (submodule → zelara-ai/module-green)
├── recycling/                          (starter feature, included by default)
├── carbon-footprint/                   (submodule → zelara-ai/module-green-carbon)
│   └── solar-calculator/               (nested submodule → zelara-ai/module-green-carbon-solar)
└── transportation/                     (submodule → zelara-ai/module-green-transport)
```

Unlock progression:
1. Green module unlocked → `recycling` available
2. Complete recycling tasks → unlock `carbon-footprint`
3. Own a home → unlock `solar-calculator` within carbon-footprint

## Build System Integration

Build system reads user's unlock state and:
1. Pulls relevant submodules from git
2. Compiles only those modules into app binary
3. User's app contains only unlocked features

Example:
- User A unlocked finance + productivity → their app includes `modules/finance` + `modules/productivity`
- User B unlocked green only → their app includes `modules/green` only
- Different users have different app binaries

## Mobile App Architecture Principle

All mobile applications are independent React Native projects with their own package names,
native modules, and App Store presence from v0.6.0 onward. There is no "embed in main app,
extract later" pattern.

- **Shared business logic**: lives in `src/packages/` as pure TypeScript packages
  (no `react-native` imports). Each package is independently testable in Node.js.
- **Shared RN infrastructure** (DeviceLinkingService, BLEDiscoveryService,
  ZelaraPinnedWebSocket, native TLS Kotlin modules): intentionally duplicated per app.
  Duplication keeps each app independently buildable and deployable without cross-app
  native dependencies.
- **No shared UI component library**: each app maintains its own components.

## Open Questions

1. **Module granularity**: One repo per major feature (finance, productivity, green)?
   - Decision deferred — current answer is one repo per domain, nested submodules later if needed.

2. **Starter features**: Where does recycling (starter) live?
   - Currently in `apps/mobile/src/` — eventual home is `modules/green/` submodule.

3. **Create all repos upfront or as needed?**
   - `apps/finance-mobile/` and `apps/testing-mobile/` created in v0.6.0.
   - Module repos created as implementation begins for each module.

---

*This document will be updated as repository structure solidifies.*