car64

<p align="center">
  <img src="assets/icon/app_icon.png" alt="car64 logo" width="120" />
</p>

<h1 align="center">car64</h1>

<p align="center">
  A modern Flutter + Supabase app for tracking and managing die-cast car collections.
</p>

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Prerequisites](#prerequisites)
- [Configuration](#configuration)
- [Getting Started](#getting-started)
- [VS Code Workflows](#vs-code-workflows)
- [Project Structure (high level)](#project-structure-high-level)
- [Troubleshooting](#troubleshooting)
- [Release Checklist](#release-checklist)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [Security Notes](#security-notes)
- [License](#license)
- [Reference](#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:

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

### Option B: direct dart-define flags

```bash
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

```bash
flutter pub get
```

2. Run analyze

```bash
flutter analyze
```

3. Launch app

```bash
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 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`
- Database and backend notes: `DB_README.md`