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 your local launch config.

• 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)

Task definition file: .vscode/tasks.json

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 strategy, commit message rules, 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

This project is licensed under the MIT License. See LICENSE for details.

Reference

• Contributor guidelines: CONTRIBUTING.md
• Security policy: SECURITY.md
• DB schema export query pack: db/export_schema.sql