Skip to content

Repository Structure

Jump to bottom
arudaev edited this page Apr 6, 2026 · 3 revisions

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/app-finance-mobile) — Zelara Finance (ai.zelara.finance)
│   │   ├── wikis/                      (submodule → zelara-ai/app-finance-mobile.wiki)
│   │   └── README.md                   (finance app overview)
│   ├── testing-mobile/                 (submodule → zelara-ai/app-testing-mobile) — Zelara Testing (ai.zelara.testing)
│   │   └── 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 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.

Clone this wiki locally