forked from jsnbuchanan/crowd-funder-for-time-pwa
205 lines
7.9 KiB
Markdown
205 lines
7.9 KiB
Markdown
# TimeSafari.app - Crowd-Funder for Time - PWA
|
|
|
|
[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.
|
|
|
|
## Roadmap
|
|
|
|
See [ClickUp](https://sharing.clickup.com/9014278710/l/h/8cmnyhp-174/10573fec74e2ba0) for current priorities.
|
|
|
|
## 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.
|
|
|
|
```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
|
|
```
|
|
|
|
### 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.
|
|
|
|
## Icons
|
|
|
|
Application icons are in the `assets` directory, processed by the `capacitor-assets` command.
|
|
|
|
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:
|
|
|
|
* `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/)
|