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

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
dialog-styles-unified
Matthew Raymer 1 day ago
parent
d663c52f2d
commit
d5786e5131
3 changed files with 448 additions and 228 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 290
      README-BUILD-GUARD.md
  2. 82
      README-PR-TEMPLATE.md
  3. 304
      README.md

290
README-BUILD-GUARD.md
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
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.

304
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
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 start:
* 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.
### Quick Setup
```bash
npm install
npm run build:web:serve -- --test
```
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
```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 guard:setup # Install and activate the guard
```
### Available Levels
### How It Works
- **`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
- **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.
See [Logging Configuration Guide](doc/logging-configuration.md) for complete details.
### Usage
### Quick Usage
```bash
# Run the database clearing script
./scripts/clear-database.sh
# Test the guard manually
npm run guard:test
# Then restart your development server
npm run build:electron:dev # For Electron
npm run build:web:dev # For Web
# Emergency bypass (use sparingly)
git commit --no-verify
git push --no-verify
```
### 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
**📚 Full documentation**: See `README-BUILD-GUARD.md`
### Manual Commands (if needed)
## 🚀 Quick Start
#### **Electron Database Location**
```bash
# Linux
rm -rf ~/.config/TimeSafari/*
### Prerequisites
# macOS
rm -rf ~/Library/Application\ Support/TimeSafari/*
- Node.js 18+
- npm, yarn, or pnpm
- Git
# Windows
rmdir /s /q %APPDATA%\TimeSafari
```
### Installation
#### **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`;
npm install
npm run guard:setup # Sets up Build Architecture Guard
```
### 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
### Development
```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 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
```
### Environment Setup & Dependencies
Before building the application, ensure your development environment is properly
configured:
### Testing
```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
npm run test:web # Run web tests
npm run test:mobile # Run mobile tests
npm run test:all # Run all tests
```
**Common Issues & Solutions**:
- **"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
**Required Versions**:
- Node.js: 18+ (LTS recommended)
- npm: 8+ (comes with Node.js)
- Platform-specific tools: Android Studio, Xcode (for mobile builds)
### Platform Support
- **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)
### Font Awesome Icons
To add a Font Awesome icon, add to `fontawesome.ts` and reference with
`font-awesome` element and `icon` attribute with the hyphenated name.
## Other
### Reference Material
* 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:
## 📁 Project Structure
```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
```
* `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
## 🔧 Build System
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
This project supports multiple platforms:
### Database Architecture
- **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
The application uses a platform-agnostic database layer with Vue mixins for service access:
## 📚 Documentation
* `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)
- **`BUILDING.md`** - Complete build system guide
- **`README-BUILD-GUARD.md`** - Build Architecture Guard documentation
- **`pull_request_template.md`** - PR template for build changes
**Development Guidelines**:
## 🤝 Contributing
- 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()`
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
**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.
## 📄 License
### Kudos
[Add your license information here]
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.

Write Preview
Loading…
Cancel
Save