Skip to content

Repository Branch Strategy

Purpose

This repository is operated as a branch-partitioned workspace.

Each long-lived branch is treated as its own project surface, even though the repository name is shared.

Branch Roles

Branch Role Scope
main Portfolio / coordination branch High-level project state only
backend-rag Backend project branch Backend code, backend docs, backend tests, backend infra
ui-nextjs-admin Admin project branch Next.js admin dashboard only
ui-flutter-chat Flutter project branch Flutter chat client only
ui-react-native-chat React Native project branch React Native chat client only

Branch Rules

main

main should contain only high-level project state.

Examples:

  • cross-project status
  • roadmap-level notes
  • top-level repository organization guidance

It should not be treated as the daily implementation branch for backend, admin, Flutter, or React Native work.

backend-rag

backend-rag is treated as an independent backend project.

Work in this branch should assume:

  • backend code is authoritative here
  • backend documentation in docs/ is authoritative for this branch
  • migrations, backend tests, deployment files, and runbooks belong here
  • code from UI branches must not be assumed to exist here

ui-nextjs-admin

ui-nextjs-admin is treated as an independent admin project for the Next.js dashboard.

ui-flutter-chat

ui-flutter-chat is treated as an independent Flutter client project.

ui-react-native-chat

ui-react-native-chat is treated as an independent React Native client project.

Feature Branching Strategy

Feature work should branch from the relevant project branch and merge back into that same project branch.

Examples:

  • backend feature branch → base backend-rag → PR into backend-rag
  • admin feature branch → base ui-nextjs-admin → PR into ui-nextjs-admin
  • Flutter feature branch → base ui-flutter-chat → PR into ui-flutter-chat
  • React Native feature branch → base ui-react-native-chat → PR into ui-react-native-chat

Practical Guidance

  • Do not treat this repository as a fully shared monorepo where every app exists on every branch.
  • Prefer the current branch state over assumptions from other branches.
  • Keep branch-local docs aligned with branch-local code.
  • If work spans multiple project branches, handle it as separate branch-scoped changes.