ParFormance

A modern, mobile‑first application built with Vue 3, Vite, and Capacitor for the web, Android, and iOS. The project structure and tooling make it easy to develop, build, and ship cross‑platform apps.

• About
• Features
• UX Philosophy
• Tech stack
• Prerequisites
• Getting started
• Scripts
• Configuration
• Development
• Building for production
• Running on mobile (Capacitor)
• Docker usage
• Project structure
• Troubleshooting
• Contributing
• License
• Storybook

About

ParFormance is a modern golf training companion designed to make practice measurable, motivating, and fun.
It combines structured drills, lightweight analytics, and an intuitive UX that helps players track their progress over time — all within a single cross-platform app.

Built with Vue 3, Tailwind, and Capacitor, ParFormance runs seamlessly on web, Android, and iOS.

Features

• Drill Catalog — categorized by Putting, Chipping, Pitching, Range, Course, Tempo, and more, complete with tag & category filtering
• Smart Shuffle (🎰 Slot Machine) — randomized drill selection with animated reels, favorites-bias, and live-synchronization with active catalog filters
• Drill Details — clear setup, step-by-step flow, and measurable targets
• Favorites & History — quick access to starred drills and past sessions
• Progress Analytics — radar charts, micro-trends, and personal-best badges
• User Settings — HCP, language, units, native Dark Mode, and data export/import
• Offline Mode — data stored locally via IndexedDB
• Native Experience — Haptic feedback interactions and seamless route transitions for mobile devices
• Responsive Design — fully optimized responsive layout for mobile and tablet

UX Philosophy

“As little text as necessary, as much clarity as possible.”

Every drill answers three questions:

1. What do I need?
2. How does it work?
3. How do I see that I’m improving?

The app’s flow follows a simple loop:
Shuffle → Drill → Session → Result → History → Progress

Tech stack

• Vue 3 (Composition API)
• Vite 6
• Tailwind CSS
• Capacitor 7 (Android and iOS)
• Pinia for state management
• Framer Motion for animations

Prerequisites

• Node.js: >= 20.19 or >= 22.12 (as defined in package.json engines)
• npm (comes with Node.js) or another package manager
• Git
• For Android builds: Android Studio, Android SDK, and Java JDK 17
• For iOS builds (macOS only): Xcode and CocoaPods
• Optional for Docker:
  • Docker Engine 24+

Verify your versions:

• node -v
• npm -v
• java -version (for Android)

Getting started

1. Clone the repository
   • git clone https://github.com/bri-b-dev/parformance.git
   • cd parformance
2. Install dependencies
   • npm install
3. Start the development server
   • npm run dev
4. Open the app
   • The dev server URL will be shown in the terminal (typically http://localhost:5173)

Scripts

The following scripts are available in package.json:

• npm run dev: Start the Vite development server
• npm run build: Build the production bundle to dist/
• npm run preview: Preview the production build locally
• npm run test: Placeholder; returns success until tests are added
• npm run lint: Placeholder; returns success until linters are configured
• npm run validate:drills: Validate drills JSON schema (src/data/drills.json)

Configuration

• Capacitor: capacitor.config.json
  • appId: com.bribdev.parformance
  • appName: ParFormance
  • webDir: dist
• Vite environment variables
  • Create .env, .env.development, or .env.production at the project root
  • Prefix variables with VITE_ to expose them to client code (for example, VITE_API_URL)

Development

• Web development
  • npm run dev
  • Edit files in src/; HMR will update the browser automatically.
• Code style and tooling
  • This project uses modern ESM and Vite. Add your preferred linters/formatters as needed.

Building for production

• Create optimized production assets in dist/
  • npm run build
• Preview the build locally
  • npm run preview

Running on mobile (Capacitor)

Capacitor bridges the web app to native platforms.

Initial platform setup (run once per platform):

• Android
  • npx cap add android
• iOS (macOS only)
  • npx cap add ios

Each time you change web code and want to run natively:

1. Build the web app
   • npm run build
2. Sync web assets and native plugins
   • npx cap sync
3. Open the native IDE to run on device or emulator
   • Android Studio: npx cap open android
   • Xcode: npx cap open ios

You can also run directly from the IDE and manage signing, emulators, and devices there.

Docker usage

Build a production image:

• docker build -t parformance:latest .

Run the container (serves dist/ via NGINX):

• docker run --rm -p 8080:80 parformance:latest

Then open http://localhost:8080

Project structure

• src: Application source code (Vue components, stores, router, etc.)
• public: Static assets copied as‑is to the root of the build
• dist: Production build output (generated)
• android, ios: Native platform projects managed by Capacitor
• resources, icons: App icons and splashes (for Capacitor assets)
• vite.config.js: Vite configuration
• capacitor.config.json: Capacitor configuration

Troubleshooting

• Node version errors
  • Ensure Node.js version matches engines in package.json (>=20.19 or >=22.12).
• Android build issues
  • Use JDK 17 and ensure ANDROID_HOME/SDK paths are configured in your environment.
  • Open the android project in Android Studio and let it sync Gradle.
• iOS build issues
  • Run pod install inside ios/ if CocoaPods are used.
  • Open the ios project in Xcode and select a valid signing team.
• Capacitor platform missing
  • If you do not see android/ or ios/, run npx cap add .
• Web assets not updating in native app
  • After changes, run npm run build && npx cap sync before opening the native IDE.

Contributing

Issues and pull requests are welcome. Please open an issue to discuss changes before submitting a PR.

• Contribution guide: see CONTRIBUTING.md
• Data model overview: see docs/DATA_MODEL.md
• App workflows (List, Detail, Shuffle, Start→Save→History, Stats): see docs/WORKFLOWS.md
• How to add a drill: covered in CONTRIBUTING.md#how-to-add-a-drill-content-contribution

License

This project is licensed under the Apache License, Version 2.0.

• See the LICENSE file at the repository root.
• You may also obtain a copy at: http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.

Storybook

• Run component workshop: npm run storybook (opens at http://localhost:6006)
• Build static Storybook: npm run build-storybook (outputs to storybook-static/)
• CI: Storybook build runs on push/PR via .github/workflows/storybook.yml