docs: comprehensive documentation updates and modernization
- Update BUILDING.md with current build system information
- Modernize various README files across the project
- Update CHANGELOG.md with recent changes
- Improve documentation consistency and formatting
- Update platform-specific documentation (iOS, Electron, Docker)
- Enhance test documentation and build guides
We can't trust iOS IndexedDB to persist. I want to start delivering an app to people now, in preparation for presentations mid-June: Rotary on June 12 and Porcfest on June 17.
@ -14,7 +13,6 @@ We can't trust iOS IndexedDB to persist. I want to start delivering an app to pe
Also, with sensitive data, the accounts info should be encrypted.
# Options
* There is a community [SQLite plugin for Capacitor](https://github.com/capacitor-community/sqlite) with encryption by [SQLCipher](https://github.com/sqlcipher/sqlcipher).
@ -29,16 +27,12 @@ Also, with sensitive data, the accounts info should be encrypted.
* Not an option yet: Dexie may support SQLite in [a future version](https://dexie.org/roadmap/dexie5.0).
# Current Plan
* Implement SQLite for Capacitor & web, with encryption. That will allow us to test quickly and keep the same interface for native & web, but we don't deal with migrations for current web users.
* After that is delivered, write a migration for current web users from IndexedDB to SQLite.
# Current method calls
... which is not 100% complete because the AI that generated thus claimed no usage of 'temp' DB.
@ -80,5 +74,3 @@ Logs operations:
db.logs.get(todayKey) - Gets logs for a specific day
*This decision was made based on the current codebase architecture and team expertise. The mixin approach provides the best balance of performance, developer experience, and architectural consistency for the TimeSafari application.*
*This decision was made based on the current codebase architecture and team expertise. The mixin approach provides the best balance of performance, developer experience, and architectural consistency for the TimeSafari application.*
- [x] All scripts and configs are committed and documented
- [x] No manual file hacks remain
- [x] All build output is deterministic and reproducible
@ -28,24 +31,29 @@
- [x] Documentation (`BUILDING.md`) is up to date
## How to Build Electron
1. Run:
```bash
./scripts/build-electron.sh
```
2. Output will be in `dist-electron/`:
- `main.js`, `preload.js` in root
- `www/` contains all renderer assets
3. No manual post-processing is required
## Customization
- **Vite config:** All build output and asset handling is controlled in `vite.config.electron.mts`
- **CSS/HTML injection:** Use Vite plugins (see `electron-css-injection` in the config) for further customization
- **Build scripts:** All orchestration is in `scripts/` and documented in `BUILDING.md`
## For Future Developers
- Always use Vite plugins/config for build output changes
- Never manually edit built files or inject assets post-build
- Keep documentation and scripts in sync with the build process
---
This file documents the context and rationale for the build modernization and should be included in the repository for onboarding and future reference.
This file documents the context and rationale for the build modernization and should be included in the repository for onboarding and future reference.
- Consider re-enabling SharedArrayBuffer if usage patterns change
@ -113,4 +127,4 @@ export function transformImageUrlForCors(imageUrl: string): string {
This change prioritizes **user experience** and **community functionality** over marginal performance gains. The database still works efficiently via IndexedDB, while images now work universally without configuration.
For a community platform like Time Safari, the ability to share images from any domain is fundamental to the user experience and mission.
For a community platform like Time Safari, the ability to share images from any domain is fundamental to the user experience and mission.
1. **Service Worker**: Intercept image requests at service worker level
2. **Build-time Processing**: Pre-process images during build
3. **CDN Integration**: Use CDN with proper CORS headers
@ -237,4 +263,4 @@ testCorsImageTransformation();
This solution provides a robust, scalable approach to image loading in a cross-origin isolated environment while maintaining the benefits of SharedArrayBuffer support. The multi-tier proxy system ensures compatibility with any image source while optimizing for performance and security.
For questions or issues, refer to the troubleshooting section or consult the development team.
For questions or issues, refer to the troubleshooting section or consult the development team.
- Changed `logger.warn` to `logger.debug` for routine SQL operations
- Reduced migration logging verbosity
- Reduced migration logging verbosity
- Made database integrity checks use debug-level logging
- Kept error and completion messages at appropriate log levels
### 2. Enhanced Logger Configuration
**Problem:** No platform-specific logging controls, causing noise in Electron.
**Solution:** Updated `src/utils/logger.ts`:
- Added platform detection for Electron vs Web
- Suppressed debug and verbose logs for Electron
- Filtered out routine database operations from database logging
@ -26,28 +30,35 @@ This document summarizes the comprehensive changes made to reduce excessive cons
- Added intelligent filtering for CapacitorPlatformService messages
### 3. API Configuration Issues (Major Fix)
**Problem:** Electron was trying to use local development endpoints (localhost:3000) from saved user settings, which don't exist in desktop environment, causing:
- 400 status errors from missing local development servers
- Updated `src/constants/app.ts` to provide Electron-specific API endpoints
- **Critical Fix:** Modified `src/db/databaseUtil.ts` in `retrieveSettingsForActiveAccount()` to force Electron to use production API endpoints regardless of saved user settings
- This ensures Electron never uses localhost development servers that users might have saved
### 4. SharedArrayBuffer Logging Noise
**Problem:** Web-specific SharedArrayBuffer detection was running in Electron, creating unnecessary debug output.
**Solution:** Modified `src/main.web.ts`:
- Made SharedArrayBuffer logging conditional on web platform only
- Converted console.log statements to logger.debug
- Only show in development mode for web platform
- Reduced platform detection noise
### 5. Missing Source Maps Warnings
**Problem:** Electron DevTools was complaining about missing source maps for external dependencies.
**Solution:** Updated `vite.config.electron.mts`:
- Disabled source maps for Electron builds (`sourcemap: false`)
- Added build configuration to suppress external dependency warnings
- Prevents DevTools from looking for non-existent source map files
@ -87,14 +98,16 @@ This document summarizes the comprehensive changes made to reduce excessive cons
## Impact
### Before Cleanup:
### Before Cleanup
- 500+ lines of console output per minute
- Detailed SQL parameter logging for every operation
- API connection errors every few seconds (400 status, JSON parsing errors)
- SharedArrayBuffer warnings on every startup
- DevTools source map warnings
### After Cleanup:
### After Cleanup
- **~95% reduction** in console output
- Only errors and important status messages visible
- **No API connection errors** - Electron uses proper production endpoints
@ -106,6 +119,7 @@ This document summarizes the comprehensive changes made to reduce excessive cons
## Technical Details
### API Configuration Fix
The most critical fix was in `src/db/databaseUtil.ts` where we added:
```typescript
@ -122,6 +136,7 @@ if (process.env.VITE_PLATFORM === "electron") {
This ensures that even if users have localhost development endpoints saved in their settings, Electron will override them with production endpoints.
### Logger Enhancement
Enhanced the logger with platform-specific behavior:
```typescript
@ -135,6 +150,7 @@ if (!isElectron || !message.includes("[CapacitorPlatformService]")) {
## Testing
The changes were tested with:
- `npm run lint-fix` - 0 errors, warnings only (pre-existing)
**Cause**: Image source doesn't send required CORS headers
**Solution**: Use a supported image hosting service or add a proxy
### `ERR_NETWORK` or `ERR_INTERNET_DISCONNECTED`
**Cause**: Proxy service is unavailable
**Solution**: Check internet connection or use alternative image source
### Images Load in Production but Not Development
**Cause**: Normal behavior - development has stricter CORS requirements
**Solution**: Use supported image sources for development testing
## Best Practices
### For New Projects
1. Use supported image hosting services from the start
2. Upload user images to Imgur or similar service
3. Host critical images on your own domain with CORS enabled
### For Existing Projects
1. Identify frequently used image domains in console warnings
2. Add proxies for the most common domains
3. Gradually migrate to supported image hosting services
### For User-Generated Content
1. Provide upload functionality to supported services
2. Validate image URLs against supported domains
3. Show helpful error messages for unsupported sources
@ -140,17 +155,20 @@ createTestImageElements(); // Creates visual test panel
## Troubleshooting
### Image Not Loading?
1. Check browser console for error messages
2. Verify the domain is in the supported list
3. Test if the image loads in production mode
4. Consider adding a proxy for that domain
### Proxy Not Working?
1. Check if the target service allows proxying
2. Verify CORS headers are being set correctly
3. Test with a simpler image URL from the same domain
### Performance Issues?
1. Proxies add latency in development only
2. Production uses direct image loading
3. Consider using a local image cache for development
@ -158,6 +176,7 @@ createTestImageElements(); // Creates visual test panel
## Quick Fixes
### For Immediate Issues
```typescript
// Temporary fallback: disable CORS headers for testing
// In vite.config.common.mts, comment out:
@ -166,9 +185,11 @@ createTestImageElements(); // Creates visual test panel
// 'Cross-Origin-Embedder-Policy': 'require-corp'
// },
```
**Note**: This disables SharedArrayBuffer performance benefits.
### For Long-term Solution
- Use supported image hosting services
- Add proxies for frequently used domains
- Migrate critical images to your own CORS-enabled CDN
@ -177,4 +198,4 @@ createTestImageElements(); // Creates visual test panel
The cross-origin isolated environment is necessary for SharedArrayBuffer performance but requires careful image source management. Use the supported services, add proxies for common domains, and accept that some external images may not work in development mode.
This is a development-only limitation - production deployments work with any image source.
This is a development-only limitation - production deployments work with any image source.
- Must be served over **HTTPS** (except `localhost` for dev).
- These headers enforce **cross-origin isolation**.
### Role of CORS
- CORS **alone is not sufficient**.
- However, embedded resources (like scripts and iframes) must still include proper CORS headers if they are to be loaded in a cross-origin isolated context.
## 3. Spectre Vulnerability
### What is Spectre?
- A class of **side-channel attacks** exploiting **speculative execution** in CPUs.
- Allows an attacker to read arbitrary memory from the same address space.
### Affected Architectures
- Intel, AMD, ARM — essentially **all modern processors**.
### Why It's Still a Concern
- It's a **hardware flaw**, not just a software bug.
- Can't be fully fixed in software without performance penalties.
- New Spectre **variants** (e.g., v2, RSB, BranchScope) continue to emerge.
and rerun `npm run dev` to give yourself user #0 and others from the ETHR_CRED_DATA in [the endorser.ch test util file](https://github.com/trentlarson/endorser-ch/blob/master/test/util.js#L90)
#### Alternative 2 - boostrap single seed user
#### Alternative 2 - boostrap single seed user
In this method you will end up with two accounts in the database, one for the first boostrap user,
and the second as the primary user you will use during testing. The first user will invite the
@ -157,26 +158,30 @@ second user to the app.
1. Install dependencies and environment variables.\
In endorser-ch install dependencies and set up environment variables to allow starting it up in
development mode.
```bash
cd endorser-ch
npm clean install # or npm ci
cp .env.local .env
```
Edit the .env file's INFURA_PROJECT_ID with the value you saved earlier in the
prerequisites.\
Then create the SQLite database by running `npm run flyway migrate` with environment variables
set correctly to select the default SQLite development user as follows.
```bash
export NODE_ENV=dev
export DBUSER=sa
export DBPASS=sasa
npm run flyway migrate
```
The first run of flyway migrate may take some time to complete because the entire Flyway
```
The first run of flyway migrate may take some time to complete because the entire Flyway
distribution must be downloaded prior to executing migrations.
The default templates are located in the `Templates` root directory and currently include the following templates:
- `Templates/AppTemplate.xcprivacy`
- `Templates/FrameworkTemplate.xcprivacy`
These templates will be modified based on the API usage analysis results, especially the `NSPrivacyAccessedAPIType` entries, to generate new privacy manifests for fixes, ensuring compliance with App Store requirements.
**If adjustments to the privacy manifest template are needed, such as in the following scenarios, avoid directly modifying the default templates. Instead, use a custom template. If a custom template with the same name exists, it will take precedence over the default template for fixes.**
- Generating a non-compliant privacy manifest due to inaccurate API usage analysis.
- Modifying the reason declared in the template.
- Adding declarations for collected data.
@ -198,6 +203,7 @@ The privacy access API categories and their associated declared reasons in `Fram
### Custom Templates
To create custom templates, place them in the `Templates/UserTemplates` directory with the following structure:
@ -205,6 +211,7 @@ To create custom templates, place them in the `Templates/UserTemplates` director
Among these templates, only `FrameworkTemplate.xcprivacy` will be modified based on the API usage analysis results to adjust the `NSPrivacyAccessedAPIType` entries, thereby generating a new privacy manifest for framework fixes. The other templates will remain unchanged and will be directly used for fixes.
**Important Notes:**
- The template for a specific framework must follow the naming convention `FrameworkName.xcprivacy`, where `FrameworkName` should match the name of the framework. For example, the template for `Flutter.framework` should be named `Flutter.xcprivacy`.
- For macOS frameworks, the naming convention should be `FrameworkName.Version.xcprivacy`, where the version name is added to distinguish different versions. For a single version macOS framework, the `Version` is typically `A`.
- The name of an SDK may not exactly match the name of the framework. To determine the correct framework name, check the `Frameworks` directory in the application bundle after building the project.
@ -5,22 +5,26 @@ This directory contains custom Git hooks for the TimeSafari project.
## Debug Code Checker Hook
### Overview
The `pre-commit` hook automatically checks for debug code when committing to protected branches (master, main, production, release). This prevents debug statements from accidentally reaching production code.
### How It Works
1. **Branch Detection**: Only runs on protected branches (configurable)
2. **File Filtering**: Automatically skips test files, scripts, and documentation
3. **Pattern Matching**: Detects common debug patterns using regex
@ -5,6 +5,7 @@ Start with [README.md](./README.md). This file has more details.
## Test User Setup
### Register New User on Test Server
On the test server, User #0 has rights to register others. Import User #0 with this seed phrase:
```bash
@ -18,6 +19,7 @@ This corresponds to: `did:ethr:0x0000694B58C2cC69658993A90D3840C560f2F51F`
## Manual Testing Steps
### Identity Management
1. Create multiple identifiers:
- Go to "Your Identity" screen
- Click "Advanced"
@ -96,10 +98,10 @@ npx playwright test -c playwright.config-local.ts test-playwright/60-new-activit
```
This command allows you to:
- **Run a specific test file**: `test-playwright/60-new-activity.spec.ts`
- **Filter to a specific test**: `--grep "New offers for another user"` runs only tests with that name
- **See the browser**: `--headed` opens the browser window so you can watch the test execute
- **Use local config**: `-c playwright.config-local.ts` uses the local configuration file
This is useful when you want to observe the testing process visually rather than running tests in headless mode. It's particularly helpful for debugging test failures or understanding how the application behaves during automated testing.
Matthew Raymer
1 day ago