trent_larson/crowd-funder-for-time-pwa
4
1
Fork 2
Code Issues Pull Requests 21 Releases 5 Wiki Activity

docs: add comprehensive Build Architecture Guard documentation

Browse Source 
- 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
2025-08-20 12:59:57 +00:00
parent d663c52f2d
commit d5786e5131
3 changed files with 458 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

290
README-BUILD-GUARD.md Normal file
View 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
View 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
View File

@@ -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 **Author**: Matthew Raymer
and expand to crowd-fund with time & money, then record and see the impact of contributions. **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 ```bash
npm install 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. ### Development
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
```bash ```bash
# Show only errors npm run build:web:dev # Build web version
VITE_LOG_LEVEL=error npm run dev npm run build:ios:test # Build iOS test version
npm run build:android:test # Build Android test version
# Show warnings and errors npm run build:electron:dev # Build Electron dev version
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
``` ```
### Available Levels ### Testing
- **`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
```bash ```bash
# Generate/update asset configurations npm run test:web # Run web tests
npm run assets:config npm run test:mobile # Run mobile tests
npm run test:all # Run all tests
# 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
``` ```
### Environment Setup & Dependencies ## 📁 Project Structure
Before building the application, ensure your development environment is properly ```text
configured: timesafari/
├── 📁 src/ # Source code
```bash ├── 📁 scripts/ # Build and automation scripts
# Install all dependencies (required first time and after updates) ├── 📁 electron/ # Electron configuration
npm install ├── 📁 android/ # Android configuration
├── 📁 ios/ # iOS configuration
# Validate your development environment ├── 📁 .husky/ # Git hooks (Build Architecture Guard)
npm run check:dependencies ├── 📄 BUILDING.md # Build system documentation
├── 📄 pull_request_template.md # PR template
# Check prerequisites for testing └── 📄 README-BUILD-GUARD.md # Guard system documentation
npm run test:prerequisites
``` ```
**Common Issues & Solutions**: ## 🔧 Build System
- **"tsx: command not found"**: Run `npm install` to install devDependencies This project supports multiple platforms:
- **"capacitor-assets: command not found"**: Ensure `@capacitor/assets` is installed
- **Build failures**: Run `npm run check:dependencies` to diagnose environment issues
**Required Versions**: - **Web**: Vite-based build with service worker support
- Node.js: 18+ (LTS recommended) - **Mobile**: Capacitor-based iOS and Android builds
- npm: 8+ (comes with Node.js) - **Desktop**: Electron-based cross-platform desktop app
- Platform-specific tools: Android Studio, Xcode (for mobile builds) - **Docker**: Containerized deployment options
### Platform Support ## 📚 Documentation
- **Android**: Adaptive icons with foreground/background, monochrome support - **`BUILDING.md`** - Complete build system guide
- **iOS**: LaunchScreen storyboard preferred, splash assets when needed - **`README-BUILD-GUARD.md`** - Build Architecture Guard documentation
- **Web**: PWA icons generated during build to `dist/` (not committed) - **`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 1. **Follow the Build Architecture Guard** - Update BUILDING.md when modifying build files
`font-awesome` element and `icon` attribute with the hyphenated name. 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/). **Note**: The Build Architecture Guard is active and will block
commits/pushes that modify build files without proper documentation
* If you are deploying in a subdirectory, add it to `publicPath` in vue.config.js, eg: `publicPath: "/app/time-tracker/",` updates. See `README-BUILD-GUARD.md` for complete details.
### 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/)