Project structure

my-app/
├── AGENTS.md                 Instructions every coding agent follows
├── CLAUDE.md                 Imports AGENTS.md for Claude Code, plus Claude-only notes
├── PRODUCT.md                What the app is, who it's for, features, glossary
├── DESIGN.md                 Look and feel, what's shared and what's native, components
├── README.md
├── Makefile                  Includes .geeknative/framework.mk; add your own targets below it
├── package.json              npm workspaces (apps/web) and the geeknative dev dependency
├── contracts/
│   ├── app.json              Name, ID, version, build and default locale
│   ├── tokens.json           Colors (light and dark), spacing, radii, type
│   ├── strings/en.json       All user-facing copy (one file per locale)
│   └── icons.json            Each icon's name on iOS, Android and web
├── spec/
│   ├── features/             One spec per feature: home.md, settings.md
│   ├── navigation.md         Screens and routes
│   ├── decisions.md          Dated decisions and assumptions
│   └── parity.md             Generated by make parity
├── apps/
│   ├── ios/                  The SwiftUI app
│   ├── android/              The Kotlin and Jetpack Compose app
│   └── web/                  The React and TanStack Start app
├── .geeknative/
│   ├── framework.mk          The make targets
│   ├── playbooks/            Step-by-step guides per request type
│   ├── templates/feature.md  The feature spec template
│   ├── hooks/                Claude Code hook scripts
│   ├── lock.json             Framework version and hashes of framework files
│   └── logs/                 Full output of each check (git-ignored)
├── .claude/                  Claude Code subagents, hooks and permissions
├── .gemini/settings.json     Points Gemini CLI at AGENTS.md
└── .github/dependabot.yml    Weekly npm and Gradle dependency updates

The apps#

apps/ios/
├── App.xcodeproj             App/ and AppTests/ are synchronized folders: new files appear automatically
├── Config/                   Build settings as .xcconfig files; Identity.xcconfig is generated
├── App/
│   ├── AppMain.swift         @main: creates AppContainer and shows RootView
│   ├── Core/                 AppContainer, RootView, Navigation/Route.swift, DesignSystem/
│   ├── Features/             Home/, Settings/
│   ├── Generated/            From contracts/; never edit
│   └── Resources/            Assets.xcassets (app icon)
└── AppTests/                 Swift Testing tests

apps/android/
├── gradle/libs.versions.toml Every dependency version
├── app/build.gradle.kts      Reads app/identity.properties (generated)
├── app/src/main/kotlin/app/
│   ├── App.kt, MainActivity.kt
│   ├── core/                 AppContainer, navigation/, designsystem/
│   ├── features/             home/, settings/
│   └── generated/            From contracts/; never edit
├── app/src/main/res/         values/generated_*.xml are generated
└── app/src/test/kotlin/app/  Unit tests

apps/web/src/
├── router.tsx                Creates the router with { queryClient, container } as context
├── routes/                   One file per URL; __root.tsx is the HTML shell and site header
├── core/                     AppContainer, AppearanceEffect, designsystem/
├── features/                 home/, settings/
├── generated/                From contracts/; never edit
├── styles.css                Tailwind entry; imports generated/tokens.css
└── routeTree.gen.ts          Generated by TanStack Router; never edit

Generated files#

make gen writes these from contracts/. They're committed, so each app builds on its own, but never edited by hand.

See File ownership for which files belong to you and which to the framework.