tracktile

name	Tracktile
description	Tracktile
category	general

---

name: tracktile description: Work in the Tracktile monorepo - Android builds (EAS), MR workflow (glab), testing, and development commands for the food & beverage manufacturing platform.

Tracktile Monorepo Development

Work effectively in the Tracktile monorepo - an operating system for food & beverage manufacturers.

Repository

# Clone (first time)
git clone [e-mail]:sharokenstudio/tracktile/tracktile.git ~/tracktile

# Or with wtm (worktree manager)
wtm init [e-mail]:sharokenstudio/tracktile/tracktile.git ~/tracktile

Remote: [e-mail]:sharokenstudio/tracktile/tracktile.git Default Branch: prerelease CI: GitLab CI/CD

Monorepo Structure

tracktile/
├── apps/
│   ├── backend/           # Backend API
│   ├── frontend/          # React Native App (Web and Mobile)
│   ├── handbook/          # Internal Employee documentation (Docusaurus)
│   └── ...
├── packages/
│   ├── common/            # Shared types, utils
│   ├── ui/                # Shared UI components
│   └── ...
├── tools/                 # Build/dev tooling
├── pnpm-workspace.yaml
└── package.json

Key Technologies

• Backend: Koa, Typebox, Knex, Objection.js
• Frontend: React Native, Unistyles V3, Signals
• Mobile: React Native, Expo
• Build: pnpm workspaces, Turborepo
• Testing: Jest, cypress (e2e)

Development Workflow

Setup

cd ~/tracktile

Create Worktree for Task

# Using wtm (preferred)
wtm create fix/issue-name --from prerelease

### Before Committing - MANDATORY
```bash
# Run from repo root, IN SEQUENCE (not parallel)
pnpm typecheck    # Must pass
pnpm lint         # Must pass
pnpm test         # Must pass (or pnpm test:affected)

⚠️ NO EXCEPTIONS. All three must pass before commit/MR.

Commit & Push

git add .
git commit -m "fix(backend): descriptive message"
git push -u origin fix/issue-name

Handbook (Documentation)

The handbook (apps/handbook) is the source of truth for Tracktile's domain, architecture, and concepts.

Local: apps/handbook/docs/ Structure:

• company/ — Culture, overview
• engineering/platform/ — Apps, services, architecture
• engineering/ops/ — Logging, monitoring, access
• topics/ — Domain concepts (EDI, traceability, etc.)

When working on Tracktile:

1. Consult handbook for domain context
2. Update docs in same MR as code changes
3. Fix outdated info when found

Key Directories by Task Type

Backend Bugs/Features

• apps/backend/src/services/ — Modular Services
• apps/backend/src/shared/ — Shared backend code

Frontend Bugs/Features

• apps/frontend/src/components/ — UI components
• apps/frontend/src/pages/ — Page components
• apps/frontend/src/stores/ — Zustand stores

Database/Migrations

• apps/backend/src/migrations/ — Knex migrations

Trace/Search/Inventory/Actions (Common Bug Area)

• apps/backend/src/services/flow/ — Flow / Inventory Service
• apps/backend/src/services/entity/ — Entity services

MR Process

Opening an MR (ALWAYS use glab)

# From your feature branch, after pushing
glab mr create --fill --target-branch prerelease

# Or with explicit options
glab mr create \
  --title "fix(backend): descriptive title" \
  --description "$(cat .gitlab/merge_request_templates/Default.md)" \
  --target-branch prerelease \
  --remove-source-branch

MR Template (MANDATORY)

Always use the repo's MR template at .gitlab/merge_request_templates/Default.md. Fill in ALL sections:

## Notes
<!-- What changed and why -->

## Asana Ticket
<!-- CLICKABLE LINK - do NOT use "fixes:" or "closes:" prefix -->
[Asana #123456789](https://app.asana.com/0/0/123456789)

## Images & Looms
<!-- Screenshots or recordings if UI change -->

## Test Cases
<!-- Link to test cases if applicable -->

## Checklists
- [ ] Tested on Web
- [ ] Tested on Android (if mobile)
- [ ] Feature flagged (if new feature)
- [ ] Translations added (if user-facing text)
- [ ] Tests added/updated

MR Commands (glab)

# List open MRs
glab mr list

# View MR details
glab mr view <mr-number>

# Check MR status/CI
glab mr view <mr-number> --comments

# Merge when ready
glab mr merge <mr-number>

⚠️ NEVER use "fixes:" or "closes:" before Asana links — triggers unwanted GitLab automations.

Environment

• Pre-Release: Testing/staging environment
• Production: Live customer environment
• Local: Docker Compose for DB/Redis

Common Commands

# Start backend locally
pnpm --filter backend dev

# Start frontend locally
pnpm --filter frontend dev

# Run specific test file
pnpm --filter backend test -- path/to/test.spec.ts

# Generate migration
pnpm --filter backend migration:generate MigrationName

# Check what's affected by changes
pnpm affected

Mobile Builds (APK/AAB)

Build Android packages locally using EAS (Expo Application Services).

Build Profiles (in apps/frontend/eas.json)

Profile	Output	Purpose
local	APK	Expo development build
prerelease	APK	Pre-release environment testing
production-preview	APK	Production environment testing
production	AAB	Play Store submission

Version Management (IMPORTANT)

EAS stores version codes remotely (cli.appVersionSource: "remote" in eas.json).

Only production profile has autoIncrement: true. For all other profiles, you MUST manually increment the version before building, or the build will reuse the same version code (causing Play Store/device conflicts).

cd apps/frontend

# 1. Check current version
eas build:version:get -p android

# 2. Increment version (for non-production profiles)
# Get current, add 1, then set
CURRENT=$(eas build:version:get -p android 2>/dev/null | grep -oP 'versionCode: \K\d+')
NEXT=$((CURRENT + 1))
eas build:version:set -p android --build-version $NEXT

# Or interactively (will prompt for version)
eas build:version:set -p android

Profile	Auto-Increment?	Action Required
production	✅ Yes	None - auto-increments
production-preview	❌ No	Run eas build:version:set first
prerelease	❌ No	Run eas build:version:set first
local	❌ No	Run eas build:version:set first

Building APKs/AABs

cd apps/frontend

# STEP 1: Increment version (skip for production profile)
eas build:version:set -p android

# STEP 2: Build

# Build APK for pre-release testing
eas build --platform android --local --profile=prerelease

# Build APK for production testing
eas build --platform android --local --profile=production-preview

# Build AAB for Play Store (auto-increments, no version:set needed)
eas build --platform android --local --profile=production

# Build development APK
eas build --platform android --local --profile=local

Build Output

Local builds output to the current directory. The file will be named like:

• APK: build-*.apk
• AAB: build-*.aab

Making Builds Available

After building, share the APK/AAB:

1. Upload to a shared location (Google Drive, S3, etc.)
2. Or use eas submit for Play Store submissions
3. For internal testing, share APK directly via Slack

Prerequisites

• EAS CLI installed: npm install -g eas-cli
• Android SDK/NDK for local builds
• Logged into EAS: eas login

Troubleshooting

pnpm install fails

rm -rf node_modules pnpm-lock.yaml
pnpm install

TypeORM entity issues

Check that entity is registered in the module's TypeOrmModule.forFeature([...])

Test database issues

docker compose down -v
docker compose up -d