Coding
PromptBeginner5 minmarkdown
Markdown Converter
Agent skill for markdown-converter
7
Coding
Safarnak App – Cursor AI Repository Rules
Project Overview
promptBeginner5 min to valuemarkdown
0 views
Feb 7, 2026
Sign in to like and favorite skills
Project Overview
Sign in to like and favorite skills
Safarnak App – Cursor AI Repository Rules
Project Overview
graphql/database/schema.tsdatabase/Current Stack (as of v1.13.0)
graphql-workers-subscriptionsRepository Structure
worker/ # Cloudflare Worker resolvers and entry graphql/ # Shared GraphQL schema + operations api/ # Client GraphQL types & hooks (generated, with automatic Drizzle sync) database/ # Shared database schema and adapters ├── schema.ts # Unified schema with UUIDs (server + client tables in one file) ├── server.ts # Server adapter (Cloudflare D1) - exports getServerDB() ├── client.ts # Client adapter (Expo SQLite) - exports getLocalDB(), sync utilities ├── index.ts # Main exports (re-exports from schema, server, client) ├── types.ts # Database types └── utils.ts # UUID utilities (createId, isValidId) migrations/ # Server-only migrations (Cloudflare D1, at project root) store/ # Redux Toolkit store, slices, middleware app/ # Expo Router pages components/ # UI components & contexts constants/, hooks/, locales/ ...
Worker
worker/index.tswrangler.tomlreadGraphQLSchemagraphql/schema-loader.tsworker/queriesworker/mutationsworker/subscriptionsSubscriptionPoolGraphQL & Codegen
graphql/schema.graphqlgraphql/queries/*.graphqlyarn codegenapi/types.tsapi/hooks.tsapi/types.tsapi/hooks.tsPath Aliases (TypeScript & Metro)
"@/*" → "./*" "@components/*" → "./components/*" "@graphql/*" → "./graphql/*" "@database/*" → "./database/*" # All database schemas & client utilities "@worker/*" → "./worker/*" "@api" → "./api" "@api/*" → "./api/*" "@store" → "./store" "@store/*" → "./store/*" "@hooks" → "./hooks" "@hooks/*" → "./hooks/*" "@constants" → "./constants" "@constants/*" → "./constants/*"
Updated aliases (tsconfig + Metro):
"@/*" → "./*" # e.g., import from '@/store/...' "@ui/*" → "./ui/*" "@graphql/*" → "./graphql/*" "@database/*" → "./database/*" "@worker/*" → "./worker/*" "@api" → "./api" "@api/*" → "./api/*" "@state" → "./ui/state" # UI local state utilities "@state/*" → "./ui/state/*" "@hooks" → "./ui/hooks" "@hooks/*" → "./ui/hooks/*" "@constants" → "./constants" "@constants/*" → "./constants/*" "@locales" → "./locales" "@locales/*" → "./locales/*" "@assets" → "./assets" "@assets/*" → "./assets/*"
GraphQL Endpoint Configuration (Client)
expo.extra.graphqlUrlapp.config.jsEXPO_PUBLIC_GRAPHQL_URL_DEVEXPO_PUBLIC_GRAPHQL_URLGRAPHQL_URL_DEVGRAPHQL_URLhttp://192.168.1.51:8787/graphqlhttps://safarnak.app/graphqlapi/client.tsapp.config.jsexpo.extra.graphqlUrlCritical Rules
"type": "module"package.jsoneslint.config.mjsgraphql/api/worker/database/schema.tsschema.tsserver.tsgetServerDB(d1)client.tsgetLocalDB()schema.tsindex.tsyarn codegenapi/types.tsapi/hooks.tsclassNameyarn db:migrateworker/index.tswrangler.tomlAuth & Client Patterns
userId + username + timestampAuthorization: Bearer <token>app/(auth)isAuthenticatedSubscriptions
graphql-workers-subscriptionsSubscriptionPool/graphqlCommands Development
yarn devyarn startyarn worker:devGraphQL
yarn codegenyarn codegen:watchDatabase
yarn db:generateyarn db:migrateyarn db:studioBuild
yarn androidyarn android:newarchyarn build:debugyarn build:releaseyarn build:localQuality & Utilities
yarn lintyarn lint:fixyarn cleanVersioning & Releases (CI-driven)
package.jsonfeat:fix:package.jsonANDROID_VERSION_CODEDebugging Tips
yarn cleanwranglerhttp://localhost:8787/graphqlyarn codegen.wrangler/state/v3/d1/yarn db:migrateSecurity
Performance
React.memouseCallbackuseMemoWhen Making Changes
graphql/schema.graphqlgraphql/queries/*.graphqlyarn codegenworker/*api/hooks.tsapi/types.ts@database/server@database/clientYou are working on Safarnak, a full-stack offline-first travel application. This is a unified single-root monorepo where both client and server code coexist in the same directory structure.
worker/index.tsworker/graphql/database/schema.tssafarnak.app/ # Single root directory ├── worker/ # GraphQL resolvers (SERVER-SIDE ONLY) │ ├── index.ts # Cloudflare Worker entry point (main export, witnesses resolvers + GraphQL Yoga) │ ├── types.ts # Server-specific types │ ├── queries/ # Query resolvers: getMessages, me, getTrips, getTrip │ ├── mutations/ # Mutation resolvers: register, login, addMessage, createTrip, updateTrip │ ├── subscriptions/ # Subscription resolvers: newMessages │ └── utilities/ # Password hashing (PBKDF2), token generation ├── graphql/ # SHARED between client & worker │ ├── schema.graphql # Pure GraphQL schema definition │ ├── queries/ # Query definitions (.graphql files) │ │ ├── addMessage.graphql │ │ ├── createTrip.graphql │ │ ├── getMessages.graphql │ │ ├── getTrip.graphql │ │ ├── getTrips.graphql │ │ ├── login.graphql │ │ ├── me.graphql │ │ └── register.graphql │ ├── generated/ │ │ └── schema.d.ts # Worker schema declarations │ ├── schema-loader.ts # Worker schema loader │ └── index.ts # Shared exports only ├── api/ # Client API layer (CLIENT-SIDE ONLY) │ ├── client.ts # Apollo Client setup with auth link and DrizzleCacheStorage │ ├── cache-storage.ts # DrizzleCacheStorage - automatic Apollo → Drizzle sync on every cache write │ ├── hooks.ts # 🤖 Auto-generated React Apollo hooks (queries, mutations, subscriptions) │ ├── types.ts # 🤖 Auto-generated GraphQL types │ ├── utils.ts # Client utility functions (storage, error handling, network checks, logout, API types) │ └── index.ts # Main API exports (re-exports hooks + all utilities) ├── database/ # Shared database schema and adapters │ ├── schema.ts # Unified schema with UUIDs (server + client tables in one file) │ ├── server.ts # Server adapter (Cloudflare D1) - exports getServerDB() │ ├── client.ts # Client adapter (Expo SQLite) - exports getLocalDB(), sync utilities │ ├── index.ts # Main exports (re-exports from schema, server, client) │ ├── types.ts # Database types │ └── utils.ts # UUID utilities (createId, isValidId) ├── migrations/ # Server-only migrations (Cloudflare D1, at project root) ├── store/ # Redux state management (CLIENT) │ ├── index.ts # Store configuration with persist │ ├── hooks.ts # Typed useAppDispatch, useAppSelector │ ├── slices/ # Redux slices │ │ ├── authSlice.ts # Auth state (user, token, isAuthenticated) │ │ └── themeSlice.ts # Theme state │ └── middleware/ # Redux middleware │ └── offlineMiddleware.ts # Offline mutation queue ├── app/ # Expo Router pages (CLIENT) │ ├── _layout.tsx # Root layout with providers │ ├── (auth)/ # Authentication route group (public routes) │ │ ├── _layout.tsx # Auth routing layout │ │ ├── welcome.tsx # Welcome/onboarding page │ │ ├── login.tsx # Login page (with auto-redirect for logged-in users) │ │ └── register.tsx # Registration page (with auto-redirect for logged-in users) │ └── (app)/ # Main app route group (protected routes with tabs) │ ├── _layout.tsx # Tab bar layout (feed, explore, trips, profile) │ ├── (feed)/ # Feed tab - social posts │ ├── (explore)/ # Explore tab - search & discovery │ ├── (trips)/ # Trips tab - trip management │ └── (profile)/ # Profile tab - user account ├── components/ # React components (CLIENT) │ ├── AuthWrapper.tsx # Authentication guard component │ ├── MapView.tsx # Interactive MapLibre GL map (native) │ ├── context/ # React contexts │ │ ├── LanguageContext.tsx # i18n language switching │ │ ├── LanguageSwitcher.tsx # Language selector UI │ │ └── ThemeContext.tsx # Dark/light theme │ └── ui/ # Themed UI components │ ├── Themed.tsx # Theme-aware View/Text │ ├── ThemeToggle.tsx # Dark mode toggle │ ├── CustomText.tsx # i18n-aware text component │ └── ... # Other UI components ├── constants/ # App constants (CLIENT) │ ├── app.ts # App configuration │ ├── Colors.ts # Theme colors │ └── index.ts # Constants exports ├── hooks/ # Custom React hooks (CLIENT) ├── locales/ # i18n translations │ ├── en/translation.json # English │ └── fa/translation.json # Persian (Farsi) ├── assets/ # Static assets (images, fonts) ├── metro.config.js # Metro bundler config with NativeWind ├── babel.config.js # Babel config with NativeWind preset ├── tailwind.config.js # Tailwind CSS configuration ├── global.css # Tailwind CSS directives (@tailwind base/components/utilities) ├── wrangler.toml # Cloudflare Workers config (worker entry: worker/index.ts) ├── drizzle.config.ts # Drizzle ORM config ├── codegen.yml # GraphQL Codegen configuration ├── eslint.config.mjs # ESLint flat config (ES module) ├── app.config.js # Expo configuration ├── tsconfig.json # TypeScript config with enhanced checking └── package.json # Single package.json (no workspaces)
"@/*" → "./*" // Root files (use '@/api' not '../api') "@components/*" → "./components/*" // UI components "@graphql/*" → "./graphql/*" // Shared GraphQL definitions "@database/*" → "./database/*" // Shared database schema & adapters (schema.ts, server.ts, client.ts) "@worker/*" → "./worker/*" // Worker resolvers "@api" → "./api" // API layer (client hooks) "@api/*" → "./api/*" // API subfolder imports "@store" → "./store" // Redux store "@store/*" → "./store/*" // Store subfolder imports "@hooks" → "./hooks" // Custom React hooks "@hooks/*" → "./hooks/*" // Hooks subfolder imports "@constants" → "./constants" // App constants "@constants/*" → "./constants/*" // Constants subfolder imports "@locales" → "./locales" // i18n translations "@locales/*" → "./locales/*" // Locales subfolder imports
Shared (graphql/):
schema.graphqlqueries/*.graphqlschema-loader.tsgenerated/schema.d.tsClient-Side (api/):
client.tscache-storage.tshooks.tstypes.tsutils.tsindex.tsServer-Side (worker/):
queries/mutations/subscriptions/utilities/Worker (worker/index.ts):
import { readGraphQLSchema } from '@graphql/schema-loader'; import { Query } from './queries'; import { Mutation } from './mutations'; import { Subscription } from './subscriptions'; // GraphQL Yoga server using shared schema + resolvers
Codegen Workflow (dev-time):
graphql/schema.graphqlgraphql/queries/*.graphqlyarn codegenapi/types.tsapi/hooks.ts@api.graphqlShared Drizzle Schema (database/):
database/schema.tsuserstripstoursmessagessubscriptionsdatabase/server.tscachedUserscachedTripscachedToursdatabase/client.tsuserFieldstripFieldsServer Usage (Worker):
database/server.tsgetServerDB(d1)database/schema.tsuserstripstoursID!passwordHashaiGeneratedClient Usage:
database/client.tsgetLocalDB()database/schema.tscachedUserscachedTripsDrizzleCacheStorageWorker Resolvers:
import { getServerDB, users, trips } from '@database/server'; import { eq } from 'drizzle-orm'; const db = getServerDB(context.env.DB); const user = await db.select().from(users).where(eq(users.id, userId)).get(); // userId is a UUID string - no conversions needed!
Client Local Database:
import { getLocalDB, cachedTrips } from '@database/client'; import { eq } from 'drizzle-orm'; const db = await getLocalDB(); const trips = await db.select().from(cachedTrips).where(eq(cachedTrips.userId, userId)).all(); // Works offline - queries local SQLite database
Migrations:
yarn db:generatedatabase/schema.tsyarn db:migratedatabase/client.tsdrizzle.config.tsschema.tsserverSchemaschemaPassword Hashing (worker/utils.ts):
Token Generation:
userId + username + timestampAuth Flow:
registerloginauthLinkAuth Pages:
app/(auth)/welcome.tsxapp/(auth)/login.tsxapp/(auth)/register.tsxisAuthenticated/(app)/(auth)/loginRouting & Navigation:
(auth)app/_layout.tsxunstable_settings.initialRouteNameapp/(auth)/_layout.tsxwelcomeloginregister(app)(feed)(explore)(trips)(profile)(auth)/auth(app)/Client-Side Storage:
apollo_cache_entriessafarnak_local.dbAutomatic Sync:
api/cache-storage.tssetItem()Sync Mechanism:
DrizzleCacheStorage.setItem()apollo_cache_entriesOffline Capabilities:
Reconnect & Queue Behavior:
Network Detection:
NativeWind Configuration:
tailwind.config.jsglobal.cssapp/_layout.tsxbabel.config.jsmetro.config.jswithNativeWind()Using Tailwind Classes:
import { View, Text } from 'react-native'; export default function MyComponent() { return ( <View className="flex-1 bg-white dark:bg-black p-4"> <Text className="text-lg text-gray-800 dark:text-gray-200 font-bold"> Hello World </Text> </View> ); }
Key Features:
flex-1p-4bg-whitedark:dark:bg-blackTheme Integration:
Appearance.setColorScheme()Best Practices:
Themed.tsxclassNameFunctional Components:
interface Props { title: string; onPress: () => void; className?: string; // Optional Tailwind classes } export default function MyComponent({ title, onPress, className }: Props) { // Use hooks const { t } = useTranslation(); // Use callbacks for performance const handlePress = useCallback(() => { onPress(); }, [onPress]); return ( <View className={`p-4 ${className || ''}`}> <Text className="text-base font-semibold">{title}</Text> </View> ); }
Context Usage:
// Provide at root (_layout.tsx) <LanguageProvider> <ThemeProvider> <Stack /> </ThemeProvider> </LanguageProvider> // Consume anywhere const { currentLanguage, changeLanguage } = useLanguage();
Always type:
Development-Friendly Approach:
any@ts-ignore@ts-expect-errorUse:
@ts-expect-errorNEVER use relative imports - Always use path aliases:
@api../../api../api@store/hooks../../store/hooks@hooks/useColorScheme../../hooks/useColorScheme@constants/Colors../../constants/Colors@components/ui/Themed../../../components/ui/ThemedThis ensures consistent, maintainable imports across the entire codebase.
package.jsonapp.config.jsmastermainfeat:feature:fix:bugfix:ci:docs:chore:refactor:package.jsonANDROID_VERSION_CODEfeat:fix:Always use path aliases instead of relative imports!
Good:
import { View } from '@components/ui/Themed'; import { useLoginMutation, useMeQuery, useAddMessageMutation } from '@api'; import { useAppDispatch, useAppSelector } from '@store/hooks'; import { login } from '@store/slices/authSlice'; import { useColorScheme } from '@hooks/useColorScheme'; import { colors } from '@constants/Colors'; import { client } from '@api'; import { persistor, store } from '@store';
Better (matches current aliases):
import { useLoginMutation, useMeQuery, useAddMessageMutation } from '@api'; import { useColorScheme } from '@hooks/useColorScheme'; import { colors } from '@constants/Colors'; import { client } from '@api'; import { useAppDispatch } from '@/store/hooks'; import { login } from '@/store/slices/authSlice';
Bad:
import { View } from '../../../components/ui/Themed'; // Use @components import { useLoginMutation } from '../../api'; // Use @api import { useAppDispatch } from '../../store/hooks'; // Use @store/hooks import { login } from '../../store/slices/authSlice'; // Use @store/slices/authSlice import { useColorScheme } from '../../hooks/useColorScheme';// Use @hooks import { client } from '../api'; // Use @api
GraphQL Resolvers:
export const register = async (_, { username, password }, context) => { // Validate input if (!username || !password) { throw new Error('Username and password are required'); } // Check existing const existing = await db.select()...; if (existing) { throw new Error('User already exists'); } // Perform operation // ... };
Client Components:
const [mutate, { loading, error }] = useMutation(REGISTER_MUTATION); if (error) return <ErrorDisplay error={error} />; if (loading) return <LoadingSpinner />;
# Development yarn dev # Start both worker and client yarn start # Expo dev server only yarn worker:dev # Worker only # GraphQL Codegen yarn codegen # Generate types and hooks from GraphQL schema yarn codegen:watch # Watch mode for development # Database yarn db:generate # Generate migration from schema yarn db:migrate # Apply migrations to local D1 yarn db:studio # Open Drizzle Studio # Code Quality yarn lint # Run ESLint with developer-friendly rules yarn lint:fix # Fix linting issues automatically yarn format # Format with Prettier (optional) # Build yarn android # Run on Android yarn ios # Run on iOS yarn build:release # EAS build for production # Utilities yarn clean # Clear all caches
PascalCase.tsxAuthWrapper.tsxcamelCase.tsuseAuth.tscamelCase.tsformatDate.tsSCREAMING_SNAKE_CASEinterface UserPropsUsing translations:
import { useTranslation } from 'react-i18next'; const { t } = useTranslation(); <Text>{t('common.welcome')}</Text>
Translation files:
locales/en/translation.jsonlocales/fa/translation.jsonRTL Support:
supportsRtl=falsemetro.config.js - Metro bundler (CommonJS)
withNativeWind()global.csseslint.config.mjs - ESLint flat config (ES Module)
wrangler.toml - Cloudflare Workers
worker/index.tsmainbabel.config.js - Babel configuration
tailwind.config.js - Tailwind CSS configuration
app/**/*.{js,jsx,ts,tsx}components/**/*.{js,jsx,ts,tsx}global.css - Tailwind directives
@tailwind base@tailwind components@tailwind utilitiesapp/_layout.tsxdrizzle.config.ts - Database (Worker)
database/schema.tsserverSchemaschemamigrations/database/ - Shared Drizzle Schema
schema.tsserver.tsgetServerDB(d1)client.tsgetLocalDB()index.tsutils.ts"type": "module"database/schema.tsyarn codegenclassNameyarn cleanany@ts-expect-errorapi/hooks.tsapi/types.tsworker/index.tsmainMetro bundler issues:
yarn clean.exponode_modules/.cacheyarn start --clearWorker issues:
.wrangler/state/v3/d1/yarn db:migrateType errors:
graphql/schema.graphqlnpx tsc --noEmityarn codegenGraphQL errors:
http://localhost:8787/graphqlyarn codegenAPI/Client errors:
api/hooks.tsapi/types.tsyarn codegenworker/utils.tsReact.memouseCallbackuseMemo@/@components/@graphql/yarn codegengraphql/schema.graphql.graphqlgraphql/queries/yarn codegenapi/hooks.tsworker/mutations/worker/queries/api/import { useLoginMutation } from 'api'For Server (Worker):
database/schema.tsuserstripstourstext('id').primaryKey().$defaultFn(() => createId())serverSchemayarn db:generatedatabase/schema.tsyarn db:migrategraphql/schema.graphqlyarn codegenFor Client Cached Tables (if needed):
database/schema.tscachedUserscachedTripscachedAtlastSyncAtpendingdeletedAtclientSchemadatabase/client.tsDrizzleCacheStorageKey Points:
database/schema.tsgetServerDB(d1)@database/servergetLocalDB()@database/clientcomponents/ui/components/locales/en/locales/fa/Remember: This is a unified monorepo with perfect separation. GraphQL folder is shared, API folder is client-only, Worker folder is server-only,
database/schema.tsyarn codegen@database/server@database/client