src

Imported from Zhadowseb/FitVen (src/AGENTS.md). Install upstream with npx skills add Zhadowseb/FitVen --skill src. Copyright stays with the author.

AGENTS.md

Scope

This file applies to everything inside src/.

Source Layout

• Pages/: screen-level UI, local components, and styles
• Database/: SQLite schema, database setup, and Supabase wiring
• Repository/: data access functions close to persistence concerns
• Services/: business logic and multi-step app flows
• Contexts/: React context and app-level state
• Localization/: the translations (locales/en, locales/da), the t() function and the provider behind useTranslation()
• Resources/: shared UI components, theme, icons, and design primitives
• Sync/: sync-related flows
• Utils/: reusable helpers with minimal side effects

Structure Rules

• Keep logic close to the feature that owns it before extracting shared abstractions.
• Prefer the existing layer boundaries over bypassing them with shortcut imports or direct database calls from screens.
• When moving or renaming files, update imports in the same change.
• Reuse Resources and existing services/repositories before creating parallel patterns.

Sync Rules

• Treat Set as the lowest-level cloud sync boundary for strength workout data.
• Keep Workout_Type_Instance cloud sync focused on workout-level fields such as workout type, label, date, completion, and timer state.
• Changes to Exercise_Instance should update local state immediately and sync the owning exercise row without bypassing the established repository and service layers.
• Changes to Set rows should update local state immediately, keep the owning Exercise_Instance derived fields in sync locally, and then sync both levels in the correct parent-first order.
• Keep Run data on its own workout-level sync path until a lower-level running sync exists.

Blocking

• Everything one user can see about another is gated on a row in public.user_follows. A block deletes those rows in both directions and a trigger refuses new ones, so activity, posts, likes and push notifications all stop without any of their own policies knowing blocking exists. Keep it that way: a new follower-visible feature inherits the block for free as long as it reads through user_follows.
• Never check a block in an RLS policy expression. The policy runs as the person doing the write, and the block row they need to see belongs to somebody else, so the check silently passes. It has to be a security definer trigger or function.
• public.profiles no longer answers for strangers. Finding someone you have no relationship with goes through public.search_profiles, and the list of people you blocked through public.list_blocked_profiles — both security definer, both filtering blocks in either direction. Somebody's profile page reads through public.public_profile the same way: a fixed set of fields, nothing from profile_private, and null for a block either way.

Conventions The Code Depends On

• Every service and repository function takes db as its first argument. The screen gets it with useSQLiteContext() and passes it down.
• Import through the barrel: from "@services", not from "@services/programService". Same for @resources/ThemedComponents.
• Use a path alias instead of climbing out of the folder. The seven are @contexts, @database, @localization, @repository, @resources, @services and @utils, defined in babel.config.js and mirrored in tsconfig.json so editor navigation follows. ./ and ../ stay for a file's own neighbours. The 149 older deep imports were deliberately left alone; convert one when a change is already touching its file.
• Never alias one layer to another layer's name. 45 function names exist in both Services and Repository with the same signature, so import { xService as xRepository } sends the next reader to the wrong file. npm test fails if one reappears.
• Folders and component files are PascalCase. Service, repository and utils files are camelCase.
• Utils/ is for helpers with minimal side effects. A helper that opens the database belongs in a service.

Text The User Reads

• Every string a user sees goes through Localization/: in a component const { t } = useTranslation() from @localization, anywhere else import { t } from "@localization". A literal English string in JSX is a string Danish users read in English.
• Keys are <area>.<name>, one file per area under locales/en and locales/da, and the two files carry the same keys. npm test runs scripts/test-localization.js, which fails on a key in one language and not the other, and on a t("...") in src/ whose key exists in neither.
• Plurals are an object with one and other (and zero when it reads differently), chosen by count: t("common.sets", { count }).
• A label computed at module load (a constant array of options, say) is frozen in whatever language the app started in. Build it inside the component, or make it a function of t.
• Dates and numbers go through formatDate, formatTime and formatNumber from @localization, which use the chosen language's locale rather than the device's.
• Workout types are stored in English (Resistance, Upperbody, Run, Walk...), and a workout nobody named has its type as its label. Draw a type with workoutTypeLabel and a workout's name with workoutDisplayName(label, t, workoutType) from src/Utils/workoutTypeLabel.js; never render label or workout_type as it is, and pass the row's type - it is what tells the type fallback from a typed "Run". Only what is drawn changes - a name the user typed stays as typed, and nothing stored is translated. The one case it cannot see: the names the app gives a strength workout after its exercises ("Push", "Legs") are stored like typed ones, so "Legs" typed on one reads "Ben".

What "Exercise" Means

Five names, and they are not interchangeable:

Surprising Placements

• The global bottom navigation and the whole start-a-workout flow live in src/Resources/ThemedComponents/ThemedBottomNavigation.js and src/Resources/Components/StartWorkoutSheet.js — not in src/Pages/. The navigation is mounted in App.js outside the navigator.
• The run screen is split, but only its pure parts. Run.js is still ~4,500 lines because the GPS and Bluetooth hooks are wired into its state and cannot move without a device to test on. The maths that could move lives beside it in runDisplayUtils.js (sections, route, charts), runFormatUtils.js (pace, clock, distance), runEnduranceStats.js and runFlowOptions.js, and is the only part with tests. Put new run maths there, not back in the screen.
• The lock-screen card during a strength workout is native, outside src/: modules/live-workout and targets/widgets. What it shows is decided in Utils/liveWorkout.js and mirrored in Swift and Kotlin; see modules/live-workout/AGENTS.md before changing either.
• src/Pages/WeekPage/ is outside the active user flow, but it is still a registered route.

Related Guides

• See src/Pages/AGENTS.md for UI-specific guidance.
• See src/Database/AGENTS.md for schema and persistence guidance.
• See src/Services/AGENTS.md for the cloud sync field checklist.
• See src/Sync/AGENTS.md for which sync components actually run.