eooo-io/skillr

Write AI instructions once, sync to every tool. One canonical format (.skillr/) compiles to CLAUDE.md, .cursor/rules, Copilot, Windsurf, Cline, and OpenAI configs.

Stars: 2 Language: PHP

Source: https://github.com/eooo-io/skillr

nesjett/agent-config-manager

A CLI tool for transferring AI agent configurations (skills, tools, rules, instructions) between different platforms like GitHub Copilot, Cursor, Claude, and Windsurf.

Stars: 1 Language: TypeScript

Source: https://github.com/nesjett/agent-config-manager

mateusz-pietras/ai-sync

o CLI that keeps a canonical .ai source of rules, skills, agents, prompts, and MCP config, then generates synchronized hard-copy setups for Cursor, GitHub Copilot, and Claude Code (including dynamic instructions/docs and template-driven automation) across repositories.

Stars: 1 Language: Go

Source: https://github.com/mateusz-pietras/ai-sync

AI Coding Agent Instructions for Mathematica AI Chat App

Project Overview

This is a Next.js-based AI chat application called "Mathematica AI" that integrates with Google's Copilot AI for conversational interactions. It uses Supabase for authentication, database storage, and real-time features.

Architecture & Data Flow

Core Components

• Frontend: Next.js 15 with React 19, TypeScript, Tailwind CSS, and Shadcn UI components
• Backend: Next.js API routes handling chat interactions
• Database: Supabase PostgreSQL with custom tables for chats, messages, and user associations
• AI Integration: Google Copilot 2.5 Pro via Vercel AI SDK with streaming responses and reasoning capabilities

Database Schema

Key tables and relationships:

• chats: Stores chat sessions with chat_id (UUID), chat_name, timestamps
• messages: Core message storage with message_id (UUID), content, role (user/assistant), chat_id
• user_chats: Links users to their chats (many-to-many)
• chat_msgs: Links chats to messages (many-to-many)
• user_msgs: Extended message metadata with sender_type (user/model) and model_name

All tables use CASCADE deletes to maintain referential integrity when chats or messages are removed.

Authentication Flow

• Supabase Auth with Google OAuth enabled
• Server-side user verification in API routes
• Client-side Supabase client for real-time subscriptions

Critical Workflows

Local Development Setup

1. Start Supabase local services: supabase start
2. Run Next.js dev server: npm run dev (uses Turbopack for faster builds)
3. Access at http://localhost:3000

Chat Interaction Flow

1. User submits prompt via ChatPromptInput component
2. API route /api/chat validates auth and chat existence
3. Streams AI response from Copilot with reasoning enabled
4. Stores both user message and AI response in database
5. Updates UI with streaming content and final database state

AI Response Processing

AI responses contain structured content wrapped in tags:

<reasoning-start>
[Reasoning content with **Step Title** sections]
<reasoning-end>

<text-start>
[Main response content]
<text-end>

The Response component parses this format and renders reasoning steps as collapsible sections using ChainOfThought UI components.

Project-Specific Conventions

Component Organization

• src/components/atom/: Basic reusable components (buttons, avatars, etc.)
• src/components/layout/: Page layout components (chat body, sidebar, etc.)
• src/components/ui/: Shadcn UI components and custom variants
• Use motion/react for animations with spring transitions (stiffness: 400, damping: 20)

Naming Patterns

• Database columns: snake_case (e.g., chat_id, message_id)
• Component props: camelCase
• File names: kebab-case for components, camelCase for utilities

Error Handling

• API routes return appropriate HTTP status codes
• Client-side uses try/catch with console.error for debugging
• Database operations check for errors before proceeding

Streaming Implementation

• Use ReadableStream for server-sent events
• Parse streaming chunks for reasoning vs. text content
• Update UI progressively during streaming, refresh from DB after completion

Key Files & Examples

Chat API (src/app/api/chat/route.ts)

// Example: Storing AI response with reasoning
const content = `<reasoning-start>\n${reasoningText}\n<reasoning-end>\n\n<text-start>\n${text}\n<text-end>`;
await supabase.from("messages").insert({
    message_id: aiMessageId,
    content,
    role: "assistant",
    chat_id: chatId
});

Response Parsing (src/components/atom/response.tsx)

// Parse structured AI response format
function parseResponse(content: string): ParsedResponse {
    const reasoningStart = content.indexOf("<reasoning-start>");
    const reasoningEnd = content.indexOf("<reasoning-end>");
    // Extract reasoning and text sections
}

Database Queries

// Fetch chat messages ordered by creation time
const { data } = await supabase
    .from("messages")
    .select('message_id, content, role, created_at')
    .eq('chat_id', chatId)
    .order('created_at', { ascending: true });

Integration Points

Supabase Client Usage

• Server client: src/util/supabase/server.ts for API routes
• Client: src/util/supabase/client.ts for browser operations
• Always check auth.getUser() for authentication state

AI SDK Configuration

• Uses google("copilot-2.5-pro") model
• Enables thinking with thinkingConfig: { includeThoughts: true, thinkingBudget: 8192 }
• Streams responses with onFinish callback for database storage

Environment Variables

Required for local development:

• SUPABASE_AUTH_EXTERNAL_GOOGLE_WEB_CLIENT_ID
• SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_SECRET
• Google AI API key (configured in Supabase)

Common Patterns

Chat Creation Flow

1. Generate UUID for chat_id
2. Insert into chats table
3. Link user via user_chats table
4. Redirect to /chat/${chat_id}

Message Storage

• User messages: Insert into messages and user_msgs (sender_type: "user")
• AI messages: Insert into messages and user_msgs (sender_type: "model", model_name: "copilot-2.5-pro")

UI State Management

• Use React state for streaming content

• Refresh from database after streaming completes

• Handle temporary UI updates during loading states

• PS: Do not ever edit the migration files directly once created. Always create new migration files for schema changes.

Debugging Tips

• Check Supabase Studio at http://localhost:54323 for database state
• Monitor streaming chunks in browser console
• Verify auth state with supabase.auth.getUser()
• Use database logs for migration issues</content> <parameter name="filePath">c:\Users\Harshit Pandit\Desktop\pcm-chat.github\copilot-instructions.md

TFX50 Coding Standards

🎯 Objetivo Principal

Estas regras não são sugestões, são diretrizes mandatórias. O objetivo é produzir código C# (.NET 8+) que seja, em ordem de prioridade:

1. Seguro: Inexpugnável contra ataques comuns.
2. Correto: Livre de bugs e lógica falha.
3. Performático: Rápido e com alocação de memória mínima (Zero-Allocation sempre que possível).
4. Claro: Legível e autoexplicativo, sem necessidade de comentários.
5. Consistente: Uniforme em todo o codebase.
6. Elegante: Esteticamente agradável e fácil de navegar.
7. Manutenível: Fácil de modificar e estender sem introduzir complexidade desnecessária.
8. Testável: Facilmente coberto por testes automatizados.
9. Escalável: Projetado para crescer com o sistema.
10. Sustentável: Baixo custo de manutenção a longo prazo.
11. Profissional: Reflete as melhores práticas da indústria.
12. Alinhado com o Negócio: Suporta os objetivos e requisitos do CrediSIS.
13. Documentado: Uso adequado de XML-Doc para APIs públicas.
14. Auditável: Facilita a rastreabilidade e conformidade.
15. Moderno: Aproveita os recursos mais recentes do C# e .NET 8+.
16. Eficiente: Minimiza o uso de recursos do sistema.
17. Testes Automatizados: Facilita a criação e manutenção de testes unitários e de integração.
18. Testes Unitários: Código deve ser facilmente testável com frameworks como xUnit, NUnit ou MSTest.
19. Testes de Integração: Facilita a criação de testes que verificam a interação entre componentes.
20. Teste Profundos: Código deve ser projetado para permitir testes profundos, incluindo mocks e stubs.
21. Cobertura de Testes: Código deve ser escrito de forma a maximizar a cobertura de testes automatizados.
22. Testabilidade: Código deve ser modular e desacoplado para facilitar a testabilidade.
23. Mockabilidade: Dependências devem ser injetadas para permitir o uso de mocks em testes.
24. Validações Finais: Sempre realize build e validação final do código antes de mesclar em branches principais.
25. Execução de Teste: Execute todos os testes automatizados antes de qualquer commit final.

Padrões para orientar a escrita de código C# (.NET9 / C#13) e TypeScript neste repositório. O foco é legibilidade, performance e consistência.

Convenções de Nomenclatura

• Classes (C# e TS): inglês, prefixo X, PascalCase.
• Ex.: XUserService, XOrderProcessor.
• Interfaces (C# e TS): inglês, prefixo XI, PascalCase.
• Ex.: XIRepository, XIUserStore.
• Métodos e propriedades: PascalCase.
• Ex.: GetById, SaveChanges, LastAccessAt.
• Campos (field) no corpo da classe: prefixo _ seguido de PascalCase.
• Ex.: _Cache, _Repository, _MaxSize.
• Parâmetros de métodos: p + PascalCase.
• Ex.: pUserID, pOptions, pToken.
• Variáveis locais: mnemônicas, abreviadas, tudo em minúsculo.
• Ex.: lstua (lista de usuários ativos), frsrt (first read table).
• Quando o nome original é abreviado, comp CEP, CPF, ID, URL, HTTP, JSON, XML, SQL, DB, UI, UX, deve manter caixa alta
• Ex.: pUserID, GetByURL, LoadFromDB.
• Nomes sempre em inglês para tipos, membros e arquivos. Esta é uma ampliação das suas instruções, focada em C# (.NET 8+), para que o Copilot (e qualquer desenvolvedor) siga padrões extremamente rigorosos de qualidade, performance, segurança, coerência e elegância.

As novas seções estão marcadas e o conteúdo existente foi integrado e reforçado.

1. Convenções de Nomenclatura (C#)

Aderência estrita a estas regras é fundamental para a legibilidade.

• Classes, Structs, Enums, Records: PascalCase.
  • Ex.: UserService, OrderProcessor, CustomerStatus.
• Interfaces: Prefixo I obrigatório, seguido de PascalCase.
  • Ex.: IRepository, IUserStore, IUnitOfWork.
• Métodos e Propriedades: PascalCase.
  • Ex.: GetByIdAsync, SaveChanges, LastAccessAt, IsValid.
• Campos (Fields) Privados: Prefixo _ obrigatório, seguido de PascalCase.
  • Ex.: _Cache, _Repository, _MaxSize.
• Campos (Fields) Estáticos Privados: Prefixo s_ (para estático) seguido de PascalCase.
• Campos (Fields) de Thread-Static: Prefixo t_ (para thread) seguido de PascalCase.
• Variáveis Locais: camelCase (minúsculas). Devem ser curtas e mnemônicas.
• Parâmetros de Métodos: p (de "parâmetro") seguido de PascalCase (como nos exemplos) ou camelCase simples. Seja consistente. O exemplo original usa pPascalCase.
  • Ex.: GetById(Guid pId), UpdateUser(User pUser).

2. Estilo de Código e Elegância

O código deve ser limpo, vertical e com o mínimo de ruído visual.

• Um Tipo por Arquivo: Mandatório. O nome do arquivo (.cs) deve ser idêntico ao do tipo principal (classe, interface, struct) que ele contém.
• Sem Chaves em Blocos de Linha Única: if, else, foreach, while ou for que contenham apenas uma instrução não devem usar chaves ({}).
  • Ex.: if (pUser == null) return false;
• Retornos Antecipados (Early Returns): Mandatório. Use o padrão guard clause para validar condições no início do método e retornar imediatamente. Isso reduz o aninhamento e a carga cognitiva.
• Sem Comentários: O código deve ser autoexplicativo. A necessidade de um comentário (// ou /* */) indica que o código precisa ser refatorado para maior clareza (ex: extrair método, renomear variável).
  • Exceção Única: XML-Doc (<summary>) para APIs públicas e membros de interfaces é permitido, mas deve descrever o "quê" e não o "como".
• Evitar Métodos Anônimos e Lambdas: Regra Crítica. Evite Func<>, Action<> e expressões lambda (=>) em caminhos de execução.
  • Sempre prefira métodos nomeados (estáticos ou de instância). Isso melhora a legibilidade, facilita o debugging (profiling) e reduz alocações de delegate e closure.
  • Exceção: Configuração de startup (ex: Program.cs) onde a legibilidade é o único foco e a performance não é crítica.

3. Qualidade e Design (SOLID e Imutabilidade)

• SOLID: Os princípios SOLID não são opcionais.
  • S (Single Responsibility): Classes devem ter uma, e apenas uma, razão para mudar.
  • O (Open/Closed): Aberto para extensão (herança, implementação), fechado para modificação.
  • L (Liskov Substitution): Tipos derivados devem ser substituíveis por seus tipos base sem alterar a corretude.
  • I (Interface Segregation): Crie interfaces pequenas e focadas (IUserReader, IUserWriter) em vez de interfaces monolíticas (IUserService).
  • D (Dependency Inversion): Dependa de abstrações (IRepository), não de implementações (SqlRepository). Use Injeção de Dependência (DI) exaustivamente.
• Imutabilidade é o Padrão: Prefira imutabilidade.
  • Use record para Data Transfer Objects (DTOs) e tipos de valor.
  • Use readonly em campos privados sempre que não forem modificados após o construtor.
  • Exponha coleções como IReadOnlyCollection<T> ou IEnumerable<T>, nunca List<T>.

4. Performance Extrema (Zero-Allocation Mindset)

Seja obsessivo com alocações de memória, especialmente em caminhos críticos (hot paths).

• Não Use LINQ em Hot Paths: Evite LINQ (.Where(), .Select(), .ToList(), etc.) em código que é executado com frequência (ex: dentro de loops, processamento de requests).
  • Justificativa: LINQ aloca enumeradores, delegates e coleções intermediárias.
  • Ação: Prefira loops explícitos (for, foreach) para controle manual e zero alocação.
• Async/Await Rigoroso:
  • Use async/await para todo I/O (rede, disco, banco de dados).
  • Nunca use async void, exceto para event handlers de UI.
  • Em código de biblioteca (projetos de serviço, domínio, infra), sempre use ConfigureAwait(false) para evitar deadlocks de contexto de sincronização.
  • Use ValueTask<T> em vez de Task<T> para métodos async que podem, com frequência, completar sincronicamente (ex: retorno de cache).
• Acesso a Dados (EF Core / Dapper):
  • Projeções Sempre: Use Select (projeções) para buscar apenas os campos necessários. Nunca faça SELECT * (context.Users.ToList()).
  • Previna N+1: Sempre que carregar entidades e suas relações, use Include(), ThenInclude() ou projeções explícitas para evitar o problema N+1.
  • Não Materialize Cedo: Não chame .ToList() ou .ToArray() até o último momento necessário.
• Use Tipos de Valor (Structs): Para objetos pequenos e imutáveis que são criados em grande quantidade, prefira readonly struct para evitar pressão no Garbage Collector (GC).
• Strings e Texto:
  • Nunca concatene strings em loops usando +. Use StringBuilder.
  • Em processamento de texto de alta performance (parsing, manipulação de bytes), use Span<T> e ReadOnlySpan<T> para evitar alocações de string e cópias de buffer.
• Classes sealed: Se uma classe não foi desenhada para herança (a maioria não é), marque-a como sealed. Isso ajuda o JIT a otimizar (devirtualização).
• Parâmetros in: Use o modificador in para passar structs grandes (que não sejam readonly) por referência sem permitir modificação, evitando custos de cópia.

5. Segurança Mandatória

Código inseguro invalida todos os outros requisitos.

• Validação de Entrada: Nunca confie na entrada do usuário. Valide toda entrada (de APIs, formulários, query strings) na fronteira do sistema (Controllers, API Endpoints). Use FluentValidation ou validação de modelo.
• SQL Injection: Tolerância Zero.
  • Sempre use queries parametrizadas.
  • Com EF Core, isso é o padrão.
  • Com Dapper ou ADO.NET, use new { Id = pId } ou SqlParameter.
  • Nunca, sob nenhuma circunstância, concatene strings de entrada do usuário para formar uma query SQL.
• Gerenciamento de Segredos:
  • Não hardcodar strings de conexão, chaves de API, senhas ou tokens no código-fonte.
  • Use IConfiguration (lendo de appsettings.json, variáveis de ambiente) ou um cofre de segredos (Azure Key Vault, HashiCorp Vault).
• Autorização e Autenticação:
  • Aplique [Authorize] (ou verificação de permissão equivalente) em todos os endpoints que não sejam publicamente anônimos.
  • Não confie que o front-end fará a verificação de segurança. A API deve ser segura por si só.
• Cross-Site Scripting (XSS): Ao retornar dados que serão renderizados em HTML/JS, garanta que eles sejam devidamente encodados (Razor faz isso por padrão; APIs de frontend precisam de cuidado).
• Criptografia: Use as APIs modernas do .NET (ex: System.Security.Cryptography) para hashing de senhas (com salt) e criptografia de dados sensíveis.

6. Tratamento de Erros e Resiliência

• Não Use Exceções para Controle de Fluxo: Exceções são para casos excepcionais.
  • Para fluxos esperados (ex: "usuário não encontrado"), use o padrão Try* (ex: bool TryGetUser(Guid pId, out User pUser)) ou retorne null / *OrDefault.
• Lance Exceções Específicas: Não lance new Exception("Erro"). Lance exceções de domínio específicas (ex: new InvalidUserStateException("Usuário já está inativo.")) ou tipos padrão (ArgumentNullException, InvalidOperationException).
• Não Suprima Erros: Evite catch (Exception e) {} ou blocos catch que apenas logam o erro e continuam. Capture exceções apenas se você puder tratá-las ou adicionar contexto valioso antes de relançá-las.
• Recursos IDisposable: Use using declarations para garantir a liberação de recursos (ex: DbContext, Stream, HttpClient).
  • using var context = _factory.CreateDbContext(); (Prefira isto ao bloco using {} para reduzir aninhamento).

Resumo (Checklist de Rigor)

1. Nomenclatura: PascalCase, IInterface, _PrivadoPascal, pParametroPascal.
2. Estilo: Um tipo por arquivo. Sem chaves em linha única. Retornos antecipados.
3. Sem "Ruído": Sem comentários. Sem lambdas/anônimos em hot paths.
4. Design: SOLID, DI, Imutabilidade (record, readonly).
5. Performance: sealed, Span<T>, StringBuilder, ConfigureAwait(false).
6. SQL/EF: Sem N+1, use Select (projeção), não materialize cedo.
7. Segurança: Valide toda entrada. Use parâmetros SQL. Não hardcode segredos.

---

Fim das instruções ampliadas.

ShopTally AI Agent Instructions

Project Overview

ShopTally is an offline-first Expo React Native shop management app with a Node.js backend for AI features. Multi-tenant architecture with role-based access control (owner vs staff).

Tech Stack: TypeScript, Expo Router, PowerSync (offline sync), Supabase (PostgreSQL), Drizzle ORM, React Query, Anthropic AI SDK.

---

Architecture & Data Flow

Offline-First Sync with PowerSync

• Primary DB: PowerSync (local SQLite) syncs with Supabase when online
• Fallback: AsyncStorage for Expo Go / web development
• Key file: lib/powersync/system.ts — handles native availability checks
• When to use: Always prefer PowerSync queries when available, but fallback to AsyncStorage gracefully

Data Entities & Schema

Core entities in lib/types.ts and lib/powersync/schema.ts:

• Product: name, price, costPrice, stock, lowStockThreshold, barcode, imageUri, category, isMarketplace
• Sale: items (SaleItem[]), total, amountPaid, paymentMethod ('cash'|'transfer'|'split'|'gateway'), isCredit
• Order: items, total, customerName, status ('new'|'accepted'|'preparing'|'ready'|'delivered')
• Shop: multi-tenant container with virtual accounts (Moniepoint, OPay, Palmpay)
• User: owner or staff with role-based permissions

Context Providers (Global State)

1. AuthContext (lib/auth-context.tsx): Session, user profile, permissions, onboarding status
   • Key hook: useAuth() → { session, user, permissions, signIn, signUp, signOut, ... }
2. ShopContext (lib/shop-context.tsx): Products, sales, orders, staff, shop profile, cart
   • Key hook: useShop() → { products, sales, orders, cart, addProduct, completeSale, ... }
3. ToastContext (lib/toast-context.tsx): Toast notifications
   • Key hook: useToast() → { success, error, warning }

---

Critical Development Patterns

1. Database → App Type Conversion

PowerSync rows are untyped. Always use row converter functions:

function rowToProduct(row: Record<string, unknown>): Product {
  return {
    id: row.id as string,
    price: row.price as number,
    stock: row.stock as number,
    lowStockThreshold: (row.low_stock_threshold as number) ?? 5,
    isMarketplace: !!(row.is_marketplace as number), // SQLite stores booleans as 0/1
    // ... other fields with type casts and nullish coalescing
  };
}

See lib/shop-context.tsx for examples. Always cast and provide defaults.

2. Theming & Colors

Never hardcode colors. Always use:

import { useThemeColors } from '@/constants/colors';

const colors = useThemeColors(colorScheme); // colorScheme from useColorScheme()
// Access: colors.primary, colors.surface, colors.text, colors.danger, etc.

See constants/colors.ts for full palette (light/dark modes).

3. Permission Checks

Owner vs staff access:

const isOwner = user?.role === 'owner';
if (!isOwner) return <RestrictedView />;

// For finer control, check `permissions` object
const canDelete = permissions?.canDeleteProducts || isOwner;

4. Storage & Persistence

Use the abstraction layer in lib/storage.ts:

import { saveProducts, loadProducts } from '@/lib/storage';
// These auto-detect PowerSync vs AsyncStorage

5. Row/Column Naming Convention

• Database columns: snake_case (created_at, low_stock_threshold, is_marketplace)
• TypeScript fields: camelCase (createdAt, lowStockThreshold, isMarketplace)
• Conversion happens in row converter functions

---

File Organization

app/                          # UI screens (Expo Router file-based routing)
├── (tabs)/                   # Bottom tab-navigated screens
│   ├── index.tsx            # Dashboard/home
│   ├── products.tsx         # Product management (see attachment)
│   ├── sales.tsx            # Sales history
│   ├── orders.tsx           # Order management
│   └── reports.tsx          # Analytics
├── auth/                     # Auth flow (before login)
│   ├── login.tsx
│   ├── onboarding.tsx       # Shop setup
│   └── _layout.tsx          # Auth stack layout
├── add-product.tsx          # Create product
├── edit-product.tsx         # Edit product (params: { productId })
├── new-sale.tsx             # Checkout flow
└── _layout.tsx              # Root layout, providers

lib/                          # Core logic & context
├── auth-context.tsx         # Authentication & user state
├── shop-context.tsx         # Products, sales, orders, cart
├── storage.ts               # AsyncStorage/PowerSync abstraction
├── supabase.ts              # Supabase client
├── types.ts                 # TypeScript interfaces
├── powersync/               # Offline sync engine
│   ├── system.ts            # DB initialization & checks
│   ├── schema.ts            # PowerSync schema definition
│   ├── connector.ts         # Supabase sync connector
│   └── migration.ts         # AsyncStorage → PowerSync migration
└── [other: toast, format, i18n, etc]

components/                   # Reusable UI components
├── AIStockModal.tsx         # AI stock advisor modal
├── BarcodeScanner.tsx       # Camera-based barcode scanning
├── LoadingSpinner.tsx
└── [others]

server/                       # Node.js backend (AI endpoints)
├── index.ts                 # Express app setup
├── routes.ts                # API route definitions
├── ai.ts                    # Anthropic AI logic
└── templates/               # Email/landing page HTML

constants/
├── colors.ts                # Theme color definitions

---

Common Tasks & Patterns

Adding a New Feature Screen

1. Create file in app/feature-name.tsx or app/(tabs)/feature-name.tsx
2. Use useShop(), useAuth(), useToast() for state
3. Apply theme with useThemeColors(colorScheme)
4. Use Expo Router for navigation: router.push('/path')
5. Add haptics feedback for interactions: Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light)

Example (see app/(tabs)/products.tsx):

export default function FeatureScreen() {
  const colorScheme = useColorScheme();
  const colors = useThemeColors(colorScheme);
  const { products } = useShop();
  const { user } = useAuth();
  const toast = useToast();
  
  if (!user?.role === 'owner') {
    return <Text>Unauthorized</Text>;
  }
  
  return <View style={{ backgroundColor: colors.background }}>...</View>;
}

Updating a Product (or any entity)

1. Call shop.updateProduct(id, updates) from ShopContext
2. This syncs via PowerSync to Supabase
3. Local state updates immediately (optimistic), then syncs
4. Show toast feedback: toast.success('Product updated')

Payment Processing

• Support multiple payment methods: 'cash' | 'transfer' | 'split' | 'gateway'
• Payment gateways: 'moniepoint' | 'opay' | 'palmpay'
• Virtual accounts are stored in shop profile with balance tracking
• See lib/payment-listener.ts for webhook handling

AI Features

• Backend routes in server/routes.ts and server/ai.ts
• Call from frontend via fetch('/api/ai/insights', { method: 'POST', body: JSON.stringify(...) })
• Used by: AIStockModal, AIInsightsCard, product description generation
• API endpoints: /api/ai/insights, /api/ai/stock-advisor, /api/ai/chat, /api/ai/product-description

---

Build & Development Commands

npm run expo:dev              # Start Expo dev server (hot reload)
npm run server:dev            # Start Node.js backend (watches TSX)
npm run db:push              # Push Drizzle migrations to Supabase
npm run lint                 # Run ESLint
npm run lint:fix             # Auto-fix linting issues

For local database development, use PowerSync via Expo dev client (native build), or AsyncStorage fallback in web/Expo Go.

---

Redux Concerns & Gotchas

1. JSON in SQLite: JSON objects (items, marketplace_listing, opening_hours) stored as TEXT. Always JSON.parse() when reading, JSON.stringify() when writing.

2. Boolean as Integer: SQLite booleans stored as 0/1. Use !!(value as number) to convert.

3. Nullable Fields: Use nullish coalescing ?? with safe defaults in row converters.

4. Type Safety: All types defined in lib/types.ts. Never use any; extend types if needed.

5. Permissions: Check user?.role for coarse access. Check permissions object for fine-grained staff capabilities.

6. Sync Conflicts: PowerSync handles conflict resolution. App treats local changes as source of truth until sync completes.

7. Barcode Scanning: Requires camera permission. BarcodeScanner component shows status and errors.

8. Images: Use expo-image component, provide contentFit="cover" and fallback placeholder when imageUri is null.

---

When to Ask for Clarification

• Should this be owner-only or staff-viewable?
• What payment method combinations are allowed?
• Should this field sync across devices or stay local?
• Is this a shop-level or global setting?