{"id":49868204,"url":"https://github.com/feral-file/ff-app","last_synced_at":"2026-05-15T04:03:27.008Z","repository":{"id":349688127,"uuid":"1142265597","full_name":"feral-file/ff-app","owner":"feral-file","description":"Canonical Flutter mobile controller and library app for FF1 and The Digital Art System.","archived":false,"fork":false,"pushed_at":"2026-05-12T04:25:45.000Z","size":6719,"stargazers_count":0,"open_issues_count":28,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T05:38:47.736Z","etag":null,"topics":["digital-art","dp1","feral-file","ff1","flutter","mobile-app"],"latest_commit_sha":null,"homepage":null,"language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause-patent","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/feral-file.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-26T07:13:45.000Z","updated_at":"2026-05-11T03:31:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/feral-file/ff-app","commit_stats":null,"previous_names":["feral-file/ff-app"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/feral-file/ff-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feral-file%2Fff-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feral-file%2Fff-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feral-file%2Fff-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feral-file%2Fff-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/feral-file","download_url":"https://codeload.github.com/feral-file/ff-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feral-file%2Fff-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33053144,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["digital-art","dp1","feral-file","ff1","flutter","mobile-app"],"created_at":"2026-05-15T04:03:26.315Z","updated_at":"2026-05-15T04:03:26.997Z","avatar_url":"https://github.com/feral-file.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Feral File Mobile App\n\nCanonical Flutter mobile controller and library app for FF1 and The Digital Art System.\n\nThis repository is the canonical source for the Feral File mobile app. The app is a Band 4 presentation surface in the broader Feral File stack: it browses DP-1 Channels, Playlists, and Works, helps users build a personal collection, pairs and controls FF1 devices, and sends play and control requests into the rest of the system.\n\n## How It Fits FF1 And The Digital Art System\n\n- `FF1` is the art computer that plays art on a screen.\n- `FFP` is the reference panel for the full system experience.\n- This mobile app is the handheld setup, library, and remote-control surface.\n- The app consumes discovery, indexing, and device-control services, but it does not own publication backoffice, device runtime, or private operational policy.\n\nIn product terms: FF1 is the engine, the mobile app is setup plus remote control plus library, and DP-1 is the compatibility layer that keeps Channels, Playlists, and Works portable.\n\n## Scope And Vocabulary\n\n- Domain vocabulary is locked to `Channel`, `Playlist`, and `Work`.\n- The app is offline-first: a local seed database is the default read path.\n- The app focuses on browsing, personal collection, pairing, and playback control.\n- Exhibitions and programs are expressed through channel and playlist presentation, not new protocol object types.\n\n## Public Repo Boundary\n\nThis repo is prepared to be the public, canonical app repository.\n\n- Public here: Flutter source, tests, public contributor docs, example configuration, and CI workflows.\n- Not public here: secrets, production credentials, private strategy docs, unpublished operational runbooks, or internal service data.\n- If a change depends on private infrastructure, document the interface and expected contract without committing secret values or private documents.\n\n## Prerequisites\n\n- Flutter stable\n- Xcode for iOS builds\n- Android Studio and Android SDK for Android builds\n- Optional FF1 hardware for end-to-end pairing and playback checks\n\n## Local Setup\n\n```bash\ngit clone https://github.com/feral-file/ff-app.git\ncd ff-app\ncp .env.example .env\nflutter pub get\n```\n\nRun the app:\n\n```bash\n# Android (development flavor)\nflutter run --flavor development\n\n# iOS\nflutter run\n```\n\nFor iOS CocoaPods setup:\n\n```bash\ncd ios\npod install --repo-update\ncd ..\n```\n\n## Environment Variable Contract\n\nCopy `.env.example` to `.env` and fill only the values needed for your workflow.\n\nRequired for app startup:\n\n- `INDEXER_API_URL`\n- `INDEXER_API_KEY`\n- `FF1_RELAYER_URL`\n- `FF1_RELAYER_API_KEY`\n\nOptional runtime integrations:\n\n- `DP1_FEED_URL` and `DP1_FEED_API_KEY` for feed-backed or integration flows\n- `DOMAIN_RESOLVER_URL` and `DOMAIN_RESOLVER_API_KEY` for ENS and TNS resolution\n- `REMOTE_CONFIG_URL` to override the default remote-config document\n- `RELEASE_NOTES_MARKDOWN_URL` or `PUBDOC_URL` to load release notes\n- `FERALFILE_DOCS_URL` to override the default public legal-docs base\n- `SUPPORT_API_KEY`, `SENTRY_DSN`, `ASSET_URL`, `INDEXER_ENRICHMENT_MAX_THREADS`\n\nIntegration and seed-database tests:\n\n- `S3_BUCKET`\n- `S3_ACCESS_KEY_ID`\n- `S3_SECRET_ACCESS_KEY`\n- `S3_REGION`\n- `S3_SEED_DATABASE_OBJECT_KEY`\n\nIf the required startup keys are missing, the app will show a configuration error screen instead of booting into a broken state.\n\n## Local Verification\n\nUse the CI-aligned verification path before opening a pull request:\n\n```bash\n./scripts/verify_ci.sh\n```\n\nThat script is non-mutating except for standard dependency/cache updates and\ncoverage output. It runs:\n\n- `flutter pub get`\n- `flutter analyze`\n- `dart format --output=none --set-exit-if-changed lib test`\n- `dart run custom_lint` when `custom_lint.yaml` exists\n- `flutter test --coverage`\n\nGitHub Actions reuses the same script for Flutter static checks and unit\ncoverage. For narrower local loops or CI changed-file static checks, the same\nentrypoint supports:\n\n```bash\n./scripts/verify_ci.sh --static-only\n./scripts/verify_ci.sh --static-only --changed-static origin/main\n./scripts/verify_ci.sh --tests-only\n```\n\nChanged-file static mode falls back to full static checks when analyzer or\npackage config changes, because those files can change diagnostics outside the\ntouched Dart files.\n\nFor a quick public setup smoke check, run:\n\n```bash\n./scripts/verify_local_setup.sh\n```\n\nThat script runs:\n\n- `flutter pub get`\n- `flutter test test/unit/infra/services/release_notes_service_test.dart`\n\nIt is intentionally a lightweight smoke test for public contributors: dependency resolution plus a public-safe unit-test path that does not require private credentials or hardware.\n\nHardware-dependent FF1 flows, S3-backed seed tests, and broader integration checks need additional environment variables and are not part of the default public setup verification.\n\n## GitHub Actions\n\nPull requests run compact checks that mirror the local verification path where\npractical:\n\n- `Run unit tests`: creates `.env` from repository secrets, runs\n  `./scripts/verify_ci.sh --tests-only`, reports coverage, and uploads\n  `coverage/lcov.info`.\n- `Lint the code`: creates `.env` from repository secrets and runs the shared\n  script in changed-file static mode; separate jobs run gitleaks and\n  dotenv-linter. This preserves the existing PR lint scope while making the\n  command non-mutating.\n\nHeavier workflows are intentionally separate from the default local gate:\n\n- `Nightly integration` runs `flutter test test/integration --concurrency=1`\n  with private integration configuration.\n- `Gold Path UI Test` runs FF1/hardware-oriented patrol checks on self-hosted\n  infrastructure.\n- Release and database snapshot workflows are manual operational workflows, not\n  contributor verification gates.\n\n## Contributing\n\n- Keep terminology aligned with `Channel`, `Playlist`, and `Work`.\n- Keep changes scoped; this repo is the canonical mobile app repo, not a place for speculative system rewrites.\n- Add or update tests for behavior changes.\n- Keep `README.md` and `.env.example` in sync when setup or configuration changes.\n- Do not commit `.env`, secrets, private planning docs, or generated artifacts.\n- Use the GitHub issue and pull-request templates when opening work.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the lightweight contributor checklist.\n\n## Related Repositories\n\n- [display-protocol/dp1](https://github.com/display-protocol/dp1) for the protocol and schemas\n- [feral-file/docs](https://github.com/feral-file/docs) for public product and legal reference material\n- [feral-file/ff-indexer-v2](https://github.com/feral-file/ff-indexer-v2) for indexing and enrichment\n- [feral-file/ff-relayer](https://github.com/feral-file/ff-relayer) for device relay and connectivity\n\n## License\n\nReleased under the BSD-2-Clause Plus Patent License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fferal-file%2Fff-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fferal-file%2Fff-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fferal-file%2Fff-app/lists"}