forked from jsnbuchanan/crowd-funder-for-time-pwa
docs: add comprehensive Build Architecture Guard documentation
- Update main README with guard system overview - Create detailed guard implementation guide - Add PR template documentation and usage examples - Document opt-in hook activation process
This commit is contained in:
Matthew Raymer
290
README-BUILD-GUARD.md
Normal file
290
README-BUILD-GUARD.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# Build Architecture Guard - Husky Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
The Build Architecture Guard protects your build system by enforcing
|
||||
documentation requirements through **Git hooks**. When you modify
|
||||
build-critical files, the system automatically blocks commits/pushes
|
||||
until you update `BUILDING.md`.
|
||||
|
||||
## 🎯 **Why Husky-Only?**
|
||||
|
||||
**Advantages:**
|
||||
|
||||
- ✅ **Immediate feedback** - Hooks run before commit/push
|
||||
- ✅ **Works everywhere** - No server-side CI/CD required
|
||||
- ✅ **Simple setup** - One tool, one configuration
|
||||
- ✅ **Fast execution** - No network delays or server queues
|
||||
- ✅ **Offline support** - Works without internet connection
|
||||
|
||||
**Trade-offs:**
|
||||
|
||||
- ⚠️ **Can be bypassed** - `git commit --no-verify` or `git push --no-verify`
|
||||
- ⚠️ **Developer discipline** - Relies on team following the rules
|
||||
|
||||
## 🏗️ **Architecture**
|
||||
|
||||
```bash
|
||||
Developer Workflow:
|
||||
1. Modify build files (scripts/, vite.config.*, etc.)
|
||||
2. Try to commit → Husky pre-commit hook runs
|
||||
3. Guard script checks if BUILDING.md was updated
|
||||
4. ✅ Commit succeeds if docs updated
|
||||
5. ❌ Commit blocked if docs missing
|
||||
```
|
||||
|
||||
## 🚀 **Quick Start**
|
||||
|
||||
### 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run prepare # Sets up Husky hooks
|
||||
```
|
||||
|
||||
### 2. Test the System
|
||||
|
||||
```bash
|
||||
# Modify a build file without updating BUILDING.md
|
||||
echo "# test" >> scripts/test.sh
|
||||
|
||||
# Try to commit (should be blocked)
|
||||
git add scripts/test.sh
|
||||
git commit -m "test: add build script"
|
||||
# ❌ Hook blocks commit with helpful message
|
||||
```
|
||||
|
||||
### 3. Fix and Retry
|
||||
|
||||
```bash
|
||||
# Update BUILDING.md with your changes
|
||||
echo "## New Build Script" >> BUILDING.md
|
||||
echo "Added test.sh for testing purposes" >> BUILDING.md
|
||||
|
||||
# Now commit should succeed
|
||||
git add BUILDING.md
|
||||
git commit -m "feat: add test build script with docs"
|
||||
# ✅ Commit succeeds
|
||||
```
|
||||
|
||||
## 🔧 **How It Works**
|
||||
|
||||
### Pre-commit Hook (`.husky/pre-commit`)
|
||||
|
||||
- **When**: Every `git commit`
|
||||
- **What**: Runs `./scripts/build-arch-guard.sh --staged`
|
||||
- **Result**: Blocks commit if build files changed without BUILDING.md update
|
||||
|
||||
### Pre-push Hook (`.husky/pre-push`)
|
||||
|
||||
- **When**: Every `git push`
|
||||
- **What**: Runs `./scripts/build-arch-guard.sh --range`
|
||||
- **Result**: Blocks push if commits contain undocumented build changes
|
||||
|
||||
### Guard Script (`scripts/build-arch-guard.sh`)
|
||||
|
||||
- **Detects**: Changes to build-sensitive file patterns
|
||||
- **Validates**: BUILDING.md was updated alongside changes
|
||||
- **Reports**: Clear error messages with guidance
|
||||
|
||||
## 📁 **Protected File Patterns**
|
||||
|
||||
The guard script monitors these paths for changes:
|
||||
|
||||
```text
|
||||
Build Configuration:
|
||||
├── vite.config.* # Vite configuration
|
||||
├── capacitor.config.ts # Capacitor configuration
|
||||
├── package.json # Package configuration
|
||||
├── package-lock.json # Lock files
|
||||
├── yarn.lock
|
||||
└── pnpm-lock.yaml
|
||||
|
||||
Build Scripts:
|
||||
├── scripts/** # All build and automation scripts
|
||||
├── electron/** # Electron build files
|
||||
├── android/** # Android build configuration
|
||||
├── ios/** # iOS build configuration
|
||||
├── sw_scripts/** # Service worker scripts
|
||||
└── sw_combine.js # Service worker combination
|
||||
|
||||
Deployment:
|
||||
├── Dockerfile # Docker configuration
|
||||
└── docker/** # Docker services
|
||||
```
|
||||
|
||||
## 🎭 **Usage Scenarios**
|
||||
|
||||
### Scenario 1: Adding a New Build Script
|
||||
|
||||
```bash
|
||||
# ❌ This will be blocked
|
||||
echo '#!/bin/bash' > scripts/new-build.sh
|
||||
git add scripts/new-build.sh
|
||||
git commit -m "feat: add new build script"
|
||||
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated"
|
||||
|
||||
# ✅ This will succeed
|
||||
echo '#!/bin/bash' > scripts/new-build.sh
|
||||
echo '## New Build Script' >> BUILDING.md
|
||||
echo 'Added new-build.sh for feature X' >> BUILDING.md
|
||||
git add scripts/new-build.sh BUILDING.md
|
||||
git commit -m "feat: add new build script with docs"
|
||||
# ✅ Commit succeeds
|
||||
```
|
||||
|
||||
### Scenario 2: Updating Vite Configuration
|
||||
|
||||
```bash
|
||||
# ❌ This will be blocked
|
||||
echo 'export default { newOption: true }' >> vite.config.ts
|
||||
git add vite.config.ts
|
||||
git commit -m "config: add new vite option"
|
||||
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated"
|
||||
|
||||
# ✅ This will succeed
|
||||
echo 'export default { newOption: true }' >> vite.config.ts
|
||||
echo '### New Vite Option' >> BUILDING.md
|
||||
echo 'Added newOption for improved performance' >> BUILDING.md
|
||||
git add vite.config.ts BUILDING.md
|
||||
git commit -m "config: add new vite option with docs"
|
||||
# ✅ Commit succeeds
|
||||
```
|
||||
|
||||
## 🚨 **Emergency Bypass**
|
||||
|
||||
**⚠️ Use sparingly and only for emergencies:**
|
||||
|
||||
```bash
|
||||
# Skip pre-commit hook
|
||||
git commit -m "emergency: critical fix" --no-verify
|
||||
|
||||
# Skip pre-push hook
|
||||
git push --no-verify
|
||||
|
||||
# Remember to update BUILDING.md later!
|
||||
```
|
||||
|
||||
## 🔍 **Troubleshooting**
|
||||
|
||||
### Hooks Not Running
|
||||
|
||||
```bash
|
||||
# Reinstall hooks
|
||||
npm run prepare
|
||||
|
||||
# Check hook files exist and are executable
|
||||
ls -la .husky/
|
||||
chmod +x .husky/*
|
||||
|
||||
# Verify Git hooks path
|
||||
git config core.hooksPath
|
||||
# Should show: .husky
|
||||
```
|
||||
|
||||
### Guard Script Issues
|
||||
|
||||
```bash
|
||||
# Test guard script manually
|
||||
./scripts/build-arch-guard.sh --help
|
||||
|
||||
# Check script permissions
|
||||
chmod +x scripts/build-arch-guard.sh
|
||||
|
||||
# Test with specific files
|
||||
./scripts/build-arch-guard.sh --staged
|
||||
```
|
||||
|
||||
### False Positives
|
||||
|
||||
```bash
|
||||
# If guard blocks legitimate changes, check:
|
||||
# 1. Are you modifying a protected file pattern?
|
||||
# 2. Did you update BUILDING.md?
|
||||
# 3. Is BUILDING.md staged for commit?
|
||||
|
||||
# View what the guard sees
|
||||
git diff --name-only --cached
|
||||
```
|
||||
|
||||
## 📋 **Best Practices**
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Update BUILDING.md first** - Document changes before implementing
|
||||
2. **Test locally** - Run `./scripts/build-arch-guard.sh --staged` before committing
|
||||
3. **Use descriptive commits** - Include context about build changes
|
||||
4. **Don't bypass lightly** - Only use `--no-verify` for true emergencies
|
||||
|
||||
### For Teams
|
||||
|
||||
1. **Document the system** - Ensure everyone understands the guard
|
||||
2. **Review BUILDING.md updates** - Verify documentation quality
|
||||
3. **Monitor bypass usage** - Track when hooks are skipped
|
||||
4. **Regular audits** - Check that BUILDING.md stays current
|
||||
|
||||
### For Maintainers
|
||||
|
||||
1. **Update protected patterns** - Modify `scripts/build-arch-guard.sh` as needed
|
||||
2. **Monitor effectiveness** - Track how often the guard catches issues
|
||||
3. **Team training** - Help developers understand the system
|
||||
4. **Continuous improvement** - Refine patterns and error messages
|
||||
|
||||
## 🔄 **Customization**
|
||||
|
||||
### Adding New Protected Paths
|
||||
|
||||
Edit `scripts/build-arch-guard.sh`:
|
||||
|
||||
```bash
|
||||
SENSITIVE=(
|
||||
# ... existing patterns ...
|
||||
"new-pattern/**" # Add your new pattern
|
||||
"*.config.js" # Add file extensions
|
||||
)
|
||||
```
|
||||
|
||||
### Modifying Error Messages
|
||||
|
||||
Edit the guard script to customize:
|
||||
|
||||
- Error message content
|
||||
- File pattern matching
|
||||
- Documentation requirements
|
||||
- Bypass instructions
|
||||
|
||||
### Adding New Validation Rules
|
||||
|
||||
Extend the guard script to check for:
|
||||
|
||||
- Specific file content patterns
|
||||
- Required documentation sections
|
||||
- Commit message formats
|
||||
- Branch naming conventions
|
||||
|
||||
## 📚 **Integration with PR Template**
|
||||
|
||||
The `pull_request_template.md` works with this system by:
|
||||
|
||||
- **Guiding developers** through required documentation
|
||||
- **Ensuring consistency** across all build changes
|
||||
- **Providing checklist** for comprehensive updates
|
||||
- **Supporting L1/L2/L3** change classification
|
||||
|
||||
## 🎯 **Success Metrics**
|
||||
|
||||
Track the effectiveness of your Build Architecture Guard:
|
||||
|
||||
- **Hook execution rate** - How often hooks run successfully
|
||||
- **Bypass frequency** - How often `--no-verify` is used
|
||||
- **Documentation quality** - BUILDING.md stays current
|
||||
- **Build failures** - Fewer issues from undocumented changes
|
||||
- **Team adoption** - Developers follow the process
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active protection system
|
||||
**Architecture**: Client-side Git hooks only
|
||||
**Dependencies**: Husky, Git, Bash
|
||||
**Maintainer**: Development team
|
||||
**Related**: `pull_request_template.md`, `scripts/build-arch-guard.sh`
|
||||
82
README-PR-TEMPLATE.md
Normal file
82
README-PR-TEMPLATE.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# Pull Request Template
|
||||
|
||||
## Location
|
||||
|
||||
The Build Architecture Guard PR template is located at:
|
||||
|
||||
- **`pull_request_template.md`** (root directory)
|
||||
|
||||
## Usage
|
||||
|
||||
When creating a pull request in Gitea, this template will automatically populate the PR description with the required checklist.
|
||||
|
||||
## Template Features
|
||||
|
||||
### Change Level Classification
|
||||
|
||||
- **L1**: Minor changes, documentation updates
|
||||
- **L2**: Moderate changes, new features, environment changes
|
||||
- **L3**: Major changes, architecture changes, new platforms
|
||||
|
||||
### Required Fields for All Levels
|
||||
|
||||
- Change level selection
|
||||
- Scope and impact description
|
||||
- Commands executed and their output
|
||||
- Documentation updates (BUILDING.md)
|
||||
- Rollback verification steps
|
||||
|
||||
### Additional Requirements for L3
|
||||
|
||||
- **ADR link**: Must provide URL to Architectural Decision Record
|
||||
- **Artifacts with SHA256**: Must list artifacts with cryptographic hashes
|
||||
|
||||
## Integration
|
||||
|
||||
This template works with:
|
||||
|
||||
- **Gitea Actions**: `.gitea/workflows/build-guard.yml`
|
||||
- **Client-side hooks**: `.husky/` pre-commit and pre-push hooks
|
||||
- **Guard script**: `scripts/build-arch-guard.sh`
|
||||
|
||||
## Example Usage
|
||||
|
||||
```markdown
|
||||
### Change Level
|
||||
- [x] Level: **L2**
|
||||
|
||||
**Why:** Adding new build script for Docker deployment
|
||||
|
||||
### Scope & Impact
|
||||
- [x] Files & platforms touched: scripts/build-docker.sh,
|
||||
BUILDING.md
|
||||
- [x] Risk triggers: Docker build process changes
|
||||
- [x] Mitigations/validation done: Tested on local Docker environment
|
||||
|
||||
### Commands Run
|
||||
- [x] Web: `npm run build:web:docker` ✅
|
||||
- [x] Docker: `docker build -t test-image .` ✅
|
||||
|
||||
### Artifacts
|
||||
- [x] Names + **sha256** of artifacts/installers:
|
||||
|
||||
Artifacts:
|
||||
```text
|
||||
test-image.tar a1b2c3d4e5f6...
|
||||
```
|
||||
|
||||
### Docs
|
||||
- [x] **BUILDING.md** updated (sections): Docker deployment
|
||||
- [x] Troubleshooting updated: Added Docker troubleshooting section
|
||||
|
||||
### Rollback
|
||||
- [x] Verified steps to restore previous behavior:
|
||||
1. `git revert HEAD`
|
||||
2. `docker rmi test-image`
|
||||
3. Restore previous BUILDING.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Note**: This template is enforced by the Build Architecture Guard
|
||||
system. Complete all required fields to ensure your PR can be merged.
|
||||
324
README.md
324
README.md
@@ -1,270 +1,118 @@
|
||||
# TimeSafari.app - Crowd-Funder for Time - PWA
|
||||
# Time Safari Application
|
||||
|
||||
[Time Safari](https://timesafari.org/) allows people to ease into collaboration: start with expressions of gratitude
|
||||
and expand to crowd-fund with time & money, then record and see the impact of contributions.
|
||||
**Author**: Matthew Raymer
|
||||
**Version**: 1.0.8-beta
|
||||
**Description**: Time Safari Application
|
||||
|
||||
## Roadmap
|
||||
## 🛡️ Build Architecture Guard
|
||||
|
||||
See [ClickUp](https://sharing.clickup.com/9014278710/l/h/8cmnyhp-174/10573fec74e2ba0) for current priorities.
|
||||
This project uses **Husky Git hooks** to protect the build system
|
||||
architecture. When you modify build-critical files, the system
|
||||
automatically blocks commits until you update `BUILDING.md`.
|
||||
|
||||
## Setup & Building
|
||||
### Quick Setup
|
||||
|
||||
Quick start:
|
||||
```bash
|
||||
npm run guard:setup # Install and activate the guard
|
||||
```
|
||||
|
||||
* For setup, we recommend [pkgx](https://pkgx.dev), which installs what you need (either automatically or with the `dev` command). Core dependencies are typescript & npm; when building for other platforms, you'll need other things such as those in the pkgx.yaml & BUILDING.md files.
|
||||
### How It Works
|
||||
|
||||
- **Pre-commit**: Blocks commits if build files changed without
|
||||
BUILDING.md updates
|
||||
- **Pre-push**: Blocks pushes if commits contain undocumented build
|
||||
changes
|
||||
- **Protected paths**: `scripts/`, `vite.config.*`, `electron/`,
|
||||
`android/`, `ios/`, etc.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
# Test the guard manually
|
||||
npm run guard:test
|
||||
|
||||
# Emergency bypass (use sparingly)
|
||||
git commit --no-verify
|
||||
git push --no-verify
|
||||
```
|
||||
|
||||
**📚 Full documentation**: See `README-BUILD-GUARD.md`
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 18+
|
||||
- npm, yarn, or pnpm
|
||||
- Git
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build:web:serve -- --test
|
||||
npm run guard:setup # Sets up Build Architecture Guard
|
||||
```
|
||||
|
||||
To be able to make submissions: go to "profile" (bottom left), go to the bottom and expand "Show Advanced Settings", go to the bottom and to the "Test Page", and finally "Become User 0" to see all the functionality.
|
||||
|
||||
See [BUILDING.md](BUILDING.md) for comprehensive build instructions for all platforms (Web, Electron, iOS, Android, Docker).
|
||||
|
||||
## Development Database Clearing
|
||||
|
||||
TimeSafari provides a simple script-based approach to clear the local database (not the claim server) for development purposes.
|
||||
|
||||
## Logging Configuration
|
||||
|
||||
TimeSafari supports configurable logging levels via the `VITE_LOG_LEVEL` environment variable. This allows developers to control console output verbosity without modifying code.
|
||||
|
||||
### Quick Usage
|
||||
### Development
|
||||
|
||||
```bash
|
||||
# Show only errors
|
||||
VITE_LOG_LEVEL=error npm run dev
|
||||
|
||||
# Show warnings and errors
|
||||
VITE_LOG_LEVEL=warn npm run dev
|
||||
|
||||
# Show info, warnings, and errors (default)
|
||||
VITE_LOG_LEVEL=info npm run dev
|
||||
|
||||
# Show all log levels including debug
|
||||
VITE_LOG_LEVEL=debug npm run dev
|
||||
npm run build:web:dev # Build web version
|
||||
npm run build:ios:test # Build iOS test version
|
||||
npm run build:android:test # Build Android test version
|
||||
npm run build:electron:dev # Build Electron dev version
|
||||
```
|
||||
|
||||
### Available Levels
|
||||
|
||||
- **`error`**: Critical errors only
|
||||
- **`warn`**: Warnings and errors (default for production web)
|
||||
- **`info`**: Info, warnings, and errors (default for development/capacitor)
|
||||
- **`debug`**: All log levels including verbose debugging
|
||||
|
||||
See [Logging Configuration Guide](doc/logging-configuration.md) for complete details.
|
||||
|
||||
### Quick Usage
|
||||
```bash
|
||||
# Run the database clearing script
|
||||
./scripts/clear-database.sh
|
||||
|
||||
# Then restart your development server
|
||||
npm run build:electron:dev # For Electron
|
||||
npm run build:web:dev # For Web
|
||||
```
|
||||
|
||||
### What It Does
|
||||
|
||||
#### **Electron (Desktop App)**
|
||||
- Automatically finds and clears the SQLite database files
|
||||
- Works on Linux, macOS, and Windows
|
||||
- Clears all data and forces fresh migrations on next startup
|
||||
|
||||
#### **Web Browser**
|
||||
- Provides instructions for using custom browser data directories
|
||||
- Shows manual clearing via browser DevTools
|
||||
- Ensures reliable database clearing without browser complications
|
||||
|
||||
### Safety Features
|
||||
- ✅ **Interactive Script**: Guides you through the process
|
||||
- ✅ **Platform Detection**: Automatically detects your OS
|
||||
- ✅ **Clear Instructions**: Step-by-step guidance for each platform
|
||||
- ✅ **Safe Paths**: Only clears TimeSafari-specific data
|
||||
|
||||
### Manual Commands (if needed)
|
||||
|
||||
#### **Electron Database Location**
|
||||
```bash
|
||||
# Linux
|
||||
rm -rf ~/.config/TimeSafari/*
|
||||
|
||||
# macOS
|
||||
rm -rf ~/Library/Application\ Support/TimeSafari/*
|
||||
|
||||
# Windows
|
||||
rmdir /s /q %APPDATA%\TimeSafari
|
||||
```
|
||||
|
||||
#### **Web Browser (Custom Data Directory)**
|
||||
```bash
|
||||
# Create isolated browser profile
|
||||
mkdir ~/timesafari-dev-data
|
||||
```
|
||||
|
||||
## Domain Configuration
|
||||
|
||||
TimeSafari uses a centralized domain configuration system to ensure consistent
|
||||
URL generation across all environments. This prevents localhost URLs from
|
||||
appearing in shared links during development.
|
||||
|
||||
### Key Features
|
||||
- ✅ **Production URLs for Sharing**: All copy link buttons use production domain
|
||||
- ✅ **Environment-Specific Internal URLs**: Internal operations use appropriate
|
||||
environment URLs
|
||||
- ✅ **Single Point of Control**: Change domain in one place for entire app
|
||||
- ✅ **Type-Safe Configuration**: Full TypeScript support
|
||||
|
||||
### Quick Reference
|
||||
|
||||
```typescript
|
||||
// For sharing functionality (environment-specific)
|
||||
import { APP_SERVER } from "@/constants/app";
|
||||
const shareLink = `${APP_SERVER}/deep-link/claim/123`;
|
||||
|
||||
// For internal operations (environment-specific)
|
||||
import { APP_SERVER } from "@/constants/app";
|
||||
const apiUrl = `${APP_SERVER}/api/claim/123`;
|
||||
```
|
||||
|
||||
### Documentation
|
||||
|
||||
- [Constants and Configuration](src/constants/app.ts) - Core constants
|
||||
|
||||
## Tests
|
||||
|
||||
See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions.
|
||||
|
||||
## Asset Management
|
||||
|
||||
TimeSafari uses a standardized asset configuration system for consistent
|
||||
icon and splash screen generation across all platforms.
|
||||
|
||||
### Asset Sources
|
||||
|
||||
- **Single source of truth**: `resources/` directory (Capacitor default)
|
||||
- **Source files**: `icon.png`, `splash.png`, `splash_dark.png`
|
||||
- **Format**: PNG or SVG files for optimal quality
|
||||
|
||||
### Asset Generation
|
||||
|
||||
- **Configuration**: `config/assets/capacitor-assets.config.json`
|
||||
- **Schema validation**: `config/assets/schema.json`
|
||||
- **Build-time generation**: Platform assets generated via `capacitor-assets`
|
||||
- **No VCS commits**: Generated assets are never committed to version control
|
||||
|
||||
### Development Commands
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Generate/update asset configurations
|
||||
npm run assets:config
|
||||
|
||||
# Validate asset configurations
|
||||
npm run assets:validate
|
||||
|
||||
# Clean generated platform assets (local dev only)
|
||||
npm run assets:clean
|
||||
|
||||
# Build with asset generation
|
||||
npm run build:native
|
||||
npm run test:web # Run web tests
|
||||
npm run test:mobile # Run mobile tests
|
||||
npm run test:all # Run all tests
|
||||
```
|
||||
|
||||
### Environment Setup & Dependencies
|
||||
## 📁 Project Structure
|
||||
|
||||
Before building the application, ensure your development environment is properly
|
||||
configured:
|
||||
|
||||
```bash
|
||||
# Install all dependencies (required first time and after updates)
|
||||
npm install
|
||||
|
||||
# Validate your development environment
|
||||
npm run check:dependencies
|
||||
|
||||
# Check prerequisites for testing
|
||||
npm run test:prerequisites
|
||||
```text
|
||||
timesafari/
|
||||
├── 📁 src/ # Source code
|
||||
├── 📁 scripts/ # Build and automation scripts
|
||||
├── 📁 electron/ # Electron configuration
|
||||
├── 📁 android/ # Android configuration
|
||||
├── 📁 ios/ # iOS configuration
|
||||
├── 📁 .husky/ # Git hooks (Build Architecture Guard)
|
||||
├── 📄 BUILDING.md # Build system documentation
|
||||
├── 📄 pull_request_template.md # PR template
|
||||
└── 📄 README-BUILD-GUARD.md # Guard system documentation
|
||||
```
|
||||
|
||||
**Common Issues & Solutions**:
|
||||
## 🔧 Build System
|
||||
|
||||
- **"tsx: command not found"**: Run `npm install` to install devDependencies
|
||||
- **"capacitor-assets: command not found"**: Ensure `@capacitor/assets` is installed
|
||||
- **Build failures**: Run `npm run check:dependencies` to diagnose environment issues
|
||||
This project supports multiple platforms:
|
||||
|
||||
**Required Versions**:
|
||||
- Node.js: 18+ (LTS recommended)
|
||||
- npm: 8+ (comes with Node.js)
|
||||
- Platform-specific tools: Android Studio, Xcode (for mobile builds)
|
||||
- **Web**: Vite-based build with service worker support
|
||||
- **Mobile**: Capacitor-based iOS and Android builds
|
||||
- **Desktop**: Electron-based cross-platform desktop app
|
||||
- **Docker**: Containerized deployment options
|
||||
|
||||
### Platform Support
|
||||
## 📚 Documentation
|
||||
|
||||
- **Android**: Adaptive icons with foreground/background, monochrome support
|
||||
- **iOS**: LaunchScreen storyboard preferred, splash assets when needed
|
||||
- **Web**: PWA icons generated during build to `dist/` (not committed)
|
||||
- **`BUILDING.md`** - Complete build system guide
|
||||
- **`README-BUILD-GUARD.md`** - Build Architecture Guard documentation
|
||||
- **`pull_request_template.md`** - PR template for build changes
|
||||
|
||||
### Font Awesome Icons
|
||||
## 🤝 Contributing
|
||||
|
||||
To add a Font Awesome icon, add to `fontawesome.ts` and reference with
|
||||
`font-awesome` element and `icon` attribute with the hyphenated name.
|
||||
1. **Follow the Build Architecture Guard** - Update BUILDING.md when modifying build files
|
||||
2. **Use the PR template** - Complete the checklist for build-related changes
|
||||
3. **Test your changes** - Ensure builds work on affected platforms
|
||||
4. **Document updates** - Keep BUILDING.md current and accurate
|
||||
|
||||
## Other
|
||||
## 📄 License
|
||||
|
||||
### Reference Material
|
||||
[Add your license information here]
|
||||
|
||||
* Notifications can be type of `toast` (self-dismiss), `info`, `success`, `warning`, and `danger`.
|
||||
They are done via [notiwind](https://www.npmjs.com/package/notiwind) and set up in App.vue.
|
||||
---
|
||||
|
||||
* [Customize Vue configuration](https://cli.vuejs.org/config/).
|
||||
|
||||
* If you are deploying in a subdirectory, add it to `publicPath` in vue.config.js, eg: `publicPath: "/app/time-tracker/",`
|
||||
|
||||
### Code Organization
|
||||
|
||||
The project uses a centralized approach to type definitions and interfaces:
|
||||
|
||||
* `src/interfaces/` - Contains all TypeScript interfaces and type definitions
|
||||
* `deepLinks.ts` - Deep linking type system and Zod validation schemas
|
||||
* `give.ts` - Give-related interfaces and type definitions
|
||||
* `claims.ts` - Claim-related interfaces and verifiable credentials
|
||||
* `common.ts` - Shared interfaces and utility types
|
||||
* Other domain-specific interface files
|
||||
|
||||
Key principles:
|
||||
- All interfaces and types are defined in the interfaces folder
|
||||
- Zod schemas are used for runtime validation and type generation
|
||||
- Domain-specific interfaces are separated into their own files
|
||||
- Common interfaces are shared through `common.ts`
|
||||
- Type definitions are generated from Zod schemas where possible
|
||||
|
||||
### Database Architecture
|
||||
|
||||
The application uses a platform-agnostic database layer with Vue mixins for service access:
|
||||
|
||||
* `src/services/PlatformService.ts` - Database interface definition
|
||||
* `src/services/PlatformServiceFactory.ts` - Platform-specific service factory
|
||||
* `src/services/AbsurdSqlDatabaseService.ts` - SQLite implementation
|
||||
* `src/utils/PlatformServiceMixin.ts` - Vue mixin for database access with caching
|
||||
* `src/db/` - Legacy Dexie database (migration in progress)
|
||||
|
||||
**Development Guidelines**:
|
||||
|
||||
- Always use `PlatformServiceMixin` for database operations in components
|
||||
- Test with PlatformServiceMixin for new features
|
||||
- Use migration tools for data transfer between systems
|
||||
- Leverage mixin's ultra-concise methods: `$db()`, `$exec()`, `$one()`, `$contacts()`, `$settings()`
|
||||
|
||||
**Architecture Decision**: The project uses Vue mixins over Composition API composables for platform service access. See [Architecture Decisions](doc/architecture-decisions.md) for detailed rationale.
|
||||
|
||||
### Kudos
|
||||
|
||||
Gifts make the world go 'round!
|
||||
|
||||
* [WebStorm by JetBrains](https://www.jetbrains.com/webstorm/) for the free open-source license
|
||||
* [Máximo Fernández](https://medium.com/@maxfarenas) for the 3D [code](https://github.com/maxfer03/vue-three-ns) and [explanatory post](https://medium.com/nicasource/building-an-interactive-web-portfolio-with-vue-three-js-part-three-implementing-three-js-452cb375ef80)
|
||||
* [Many tools & libraries](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa/src/branch/master/package.json#L10) such as Nodejs.org, IntelliJ Idea, Veramo.io, Vuejs.org, threejs.org
|
||||
* [Bush 3D model](https://sketchfab.com/3d-models/lupine-plant-bf30f1110c174d4baedda0ed63778439)
|
||||
* [Forest floor image](https://www.goodfreephotos.com/albums/textures/leafy-autumn-forest-floor.jpg)
|
||||
* Time Safari logo assisted by [DALL-E in ChatGPT](https://chat.openai.com/g/g-2fkFE8rbu-dall-e)
|
||||
* [DiceBear](https://www.dicebear.com/licenses/) and [Avataaars](https://www.dicebear.com/styles/avataaars/#details) for human-looking identicons
|
||||
* Some gratitude prompts thanks to [Develop Good Habits](https://www.developgoodhabits.com/gratitude-journal-prompts/)
|
||||
**Note**: The Build Architecture Guard is active and will block
|
||||
commits/pushes that modify build files without proper documentation
|
||||
updates. See `README-BUILD-GUARD.md` for complete details.
|
||||
|
||||
Reference in New Issue
Block a user