hwhub/README.md

car64

A modern Flutter + Supabase app for tracking and managing die-cast car collections.

---

Table of Contents

• Overview
• Features
• Tech Stack
• Prerequisites
• Configuration
• Getting Started
• VS Code Workflows
• Project Structure (high level)
• Troubleshooting
• Release Checklist
• Roadmap
• Contributing
• Security Notes
• License
• Reference

Overview

car64 helps collectors scan model IDs, organize personal and shared collections, and keep a clean catalog with community validation/reporting flows.

Features

• Fast scan workflow (camera OCR + manual entry fallback)
• Multi-collection support with member roles (owner/member/viewer)
• Private image storage with signed URL access
• Collection collaboration and member management
• Community validation and issue reporting for catalog entries
• Profile/settings flows including password updates and report tracking

Tech Stack

• Flutter (Material 3)
• Supabase (Auth, PostgREST, Storage, RPC)
• Shared Preferences (local settings)
• Google ML Kit Text Recognition (scanner)

Prerequisites

• Flutter SDK (stable)
• A Supabase project
• For iOS builds: macOS + Xcode

Configuration

Supabase config is required at runtime/build time (no embedded fallback values).

Option A: local defines file (recommended)

Use:

• .env/flutter_defines.json (local, ignored by git)
• .env/flutter_defines.example.json (tracked template)

Expected shape:

{
  "SUPABASE_URL": "https://your-project.supabase.co",
  "SUPABASE_ANON_KEY": "your_anon_key",
  "SUPABASE_USE_PKCE": "true"
}

Option B: direct dart-define flags

flutter run \
  --dart-define=SUPABASE_URL=https://your-project.supabase.co \
  --dart-define=SUPABASE_ANON_KEY=your_anon_key \
  --dart-define=SUPABASE_USE_PKCE=true

Getting Started

1. Install dependencies

flutter pub get

2. Run analyze

flutter analyze

3. Launch app

flutter run

VS Code Workflows

Run / Debug (launch.json)

Use Run and Debug with:

• Flutter (Supabase Local - Debug)
• Flutter (Supabase Local - Profile)
• Flutter (Supabase Local - Release)

These configurations read:

--dart-define-from-file=.env/flutter_defines.json

Build Tasks (tasks.json)

Use Terminal → Run Task:

• Flutter Build APK (Release)
• Flutter Build App Bundle (Release)
• Flutter Build iOS IPA (Release)

Project Structure (high level)

• lib/screens/ UI screens and flows
• lib/services/ Supabase integration/services
• lib/widgets/ reusable UI components
• lib/utils/ helpers and formatting utilities
• lib/theme/ app theme and colors

Troubleshooting

App fails at startup with Supabase config error

• Ensure .env/flutter_defines.json exists locally.
• Confirm all required keys are present:
  • SUPABASE_URL
  • SUPABASE_ANON_KEY
  • SUPABASE_USE_PKCE

Build task works but app cannot connect to backend

• Verify the Supabase URL/key pair belong to the same project.
• Check Supabase RLS policies and RPC permissions.

iOS IPA task fails on Windows

• flutter build ipa requires macOS + Xcode.

Release Checklist

• flutter pub get
• flutter analyze
• Manual smoke test on Android
• Manual smoke test on iOS
• Confirm .env/flutter_defines.json points to production Supabase
• Build Android appbundle
• Build iOS ipa
• Verify auth, scan flow, collections, and upload flows

Roadmap

• Optional dark/light theme toggle in settings
• Extended scanner confidence hints and retry UX
• Bulk actions and better collection analytics
• Improved offline behavior for low-connectivity sessions

Contributing

See CONTRIBUTING.md for branching, commit style, and PR guidelines.

Security Notes

• Supabase anon keys are intentionally client-side, but RLS and RPC permissions must be strict.
• Sensitive local config files are git-ignored.
• User-facing errors are sanitized and shown via global overlays.

For reporting vulnerabilities, see SECURITY.md.

License

License file is not included in this repository yet. Add your preferred license in the GitHub repo when ready.

Reference

• Product/backend notes: TPB.md