Repository Structure

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/
│   ├── skill-tree/                     (progression system, unlock logic)
│   ├── state/                          (local-first user data, device sync)
│   ├── build/                          (conditional bundling, submodule orchestration)
│   └── device-linking/                 (cross-device communication, task offloading)
├── 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)
│   │   ├── wikis/                      (submodule → zelara-ai/app-desktop.wiki)
│   │   └── README.md                   (desktop app overview)
│   ├── mobile/                         (submodule → zelara-ai/app-mobile)
│   │   ├── wikis/                      (submodule → zelara-ai/app-mobile.wiki)
│   │   └── README.md                   (mobile app overview)
│   └── web/                            (submodule → zelara-ai/app-web)
│       ├── 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 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

Open Questions

1. Module granularity: How fine-grained should submodules be?

   • One repo per major feature (finance, productivity, green)?
   • Or separate repos for sub-features (budget, tax, email-ai, focus-timer)?

2. Shared UI components: Do apps share a UI component library?

   • Separate zelara-ai/ui-components repo?
   • Or each app maintains its own components?

3. Starter features: Where does recycling (starter) live?

   • In core (always included)?
   • In module-green (unlocked by default)?

4. App code sharing: How much code is shared between Desktop/Mobile/Web?

   • Shared business logic repo?
   • Or duplicated per app?

5. Create all repos upfront or as needed?

   • Create module repos now (even if empty)?
   • Or create only when starting implementation?

Decisions Needed

• Module granularity (one repo per feature domain vs per sub-feature)
• Shared UI component strategy
• Where starter features live (core vs module-green)
• App code sharing approach
• Repo creation timeline (upfront vs on-demand)

---

This document will be updated as repository structure solidifies.