refactor(cursor-rules): reorganize rules into logical directory structure
Restructure .cursor/rules from flat organization to hierarchical categories: - app/: application-specific rules (timesafari, architectural decisions) - database/: database-related rules (absurd-sql, legacy dexie) - development/: development workflow rules - docs/: documentation standards and markdown rules - features/: feature-specific implementation rules (camera) - workflow/: version control and workflow rules Add base_context.mdc for shared context across all rule categories. Improves maintainability and discoverability of cursor rules.
This commit is contained in:
Matthew Raymer
172
.cursor/rules/app/architectural_decision_record.mdc
Normal file
172
.cursor/rules/app/architectural_decision_record.mdc
Normal file
@@ -0,0 +1,172 @@
|
||||
---
|
||||
description:
|
||||
globs:
|
||||
alwaysApply: true
|
||||
---
|
||||
# TimeSafari Cross-Platform Architecture Guide
|
||||
|
||||
## 1. Platform Support Matrix
|
||||
|
||||
| Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) |
|
||||
|---------|-----------|--------------------|-------------------|
|
||||
| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented |
|
||||
| Deep Linking | URL Parameters | App URL Open Events | Not Implemented |
|
||||
| File System | Limited (Browser API) | Capacitor Filesystem | Electron fs |
|
||||
| Camera Access | MediaDevices API | Capacitor Camera | Not Implemented |
|
||||
| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env checks |
|
||||
|
||||
---
|
||||
|
||||
## 2. Project Structure
|
||||
|
||||
### Core Directories
|
||||
```
|
||||
src/
|
||||
├── components/ # Vue components
|
||||
├── services/ # Platform services and business logic
|
||||
├── views/ # Page components
|
||||
├── router/ # Vue router configuration
|
||||
├── types/ # TypeScript type definitions
|
||||
├── utils/ # Utility functions
|
||||
├── lib/ # Core libraries
|
||||
├── platforms/ # Platform-specific implementations
|
||||
├── electron/ # Electron-specific code
|
||||
├── constants/ # Application constants
|
||||
├── db/ # Database related code
|
||||
├── interfaces/ # TypeScript interfaces
|
||||
└── assets/ # Static assets
|
||||
```
|
||||
|
||||
### Entry Points
|
||||
- `main.ts` → Base entry
|
||||
- `main.common.ts` → Shared init
|
||||
- `main.capacitor.ts` → Mobile entry
|
||||
- `main.electron.ts` → Electron entry
|
||||
- `main.web.ts` → Web entry
|
||||
|
||||
---
|
||||
|
||||
## 3. Service Architecture
|
||||
|
||||
### Service Organization
|
||||
|
||||
```tree
|
||||
services/
|
||||
├── QRScanner/
|
||||
│ ├── WebInlineQRScanner.ts
|
||||
│ └── interfaces.ts
|
||||
├── platforms/
|
||||
│ ├── WebPlatformService.ts
|
||||
│ ├── CapacitorPlatformService.ts
|
||||
│ └── ElectronPlatformService.ts
|
||||
└── factory/
|
||||
└── PlatformServiceFactory.ts
|
||||
```
|
||||
|
||||
### Factory Pattern
|
||||
Use a **singleton factory** to select platform services via `process.env.VITE_PLATFORM`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Feature Guidelines
|
||||
|
||||
### QR Code Scanning
|
||||
- Define `QRScannerService` interface.
|
||||
- Implement platform-specific classes (`WebInlineQRScanner`, Capacitor, etc).
|
||||
- Provide `addListener` and `onStream` hooks for composability.
|
||||
|
||||
### Deep Linking
|
||||
- URL format: `timesafari://<route>[/<param>][?query=value]`
|
||||
- Web: `router.beforeEach` → parse query
|
||||
- Capacitor: `App.addListener("appUrlOpen", …)`
|
||||
|
||||
---
|
||||
|
||||
## 5. Build Process
|
||||
|
||||
- `vite.config.common.mts` → shared config
|
||||
- Platform configs: `vite.config.web.mts`, `.capacitor.mts`, `.electron.mts`
|
||||
- Use `process.env.VITE_PLATFORM` for conditional loading.
|
||||
|
||||
```bash
|
||||
npm run build:web
|
||||
npm run build:capacitor
|
||||
npm run build:electron
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Testing Strategy
|
||||
|
||||
- **Unit tests** for services.
|
||||
- **Playwright** for Web + Capacitor:
|
||||
- `playwright.config-local.ts` includes web + Pixel 5.
|
||||
- **Electron tests**: add `spectron` or Playwright-Electron.
|
||||
- Mark tests with platform tags:
|
||||
|
||||
```ts
|
||||
test.skip(!process.env.MOBILE_TEST, "Mobile-only test");
|
||||
```
|
||||
|
||||
> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15 min) with QA to align on coverage and flaky test risks.
|
||||
|
||||
---
|
||||
|
||||
## 7. Error Handling
|
||||
|
||||
- Global Vue error handler → logs with component name.
|
||||
- Platform-specific wrappers log API errors with platform prefix (`[Capacitor API Error]`, etc).
|
||||
- Use structured logging (not `console.log`).
|
||||
|
||||
---
|
||||
|
||||
## 8. Best Practices
|
||||
|
||||
- Keep platform code **isolated** in `platforms/`.
|
||||
- Always define a **shared interface** first.
|
||||
- Use feature detection, not platform detection, when possible.
|
||||
- Dependency injection for services → improves testability.
|
||||
- Maintain **Competence Hooks** in PRs (2–3 prompts for dev discussion).
|
||||
|
||||
---
|
||||
|
||||
## 9. Dependency Management
|
||||
|
||||
- Key deps: `@capacitor/core`, `electron`, `vue`.
|
||||
- Use conditional `import()` for platform-specific libs.
|
||||
|
||||
---
|
||||
|
||||
## 10. Security Considerations
|
||||
|
||||
- **Permissions**: Always check + request gracefully.
|
||||
- **Storage**: Secure storage for sensitive data; encrypt when possible.
|
||||
- **Audits**: Schedule quarterly security reviews.
|
||||
|
||||
---
|
||||
|
||||
## 11. ADR Process
|
||||
|
||||
- All major architecture choices → log in `doc/adr/`.
|
||||
- Use ADR template with Context, Decision, Consequences, Status.
|
||||
- Link related ADRs in PR descriptions.
|
||||
|
||||
> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min design sync for discussion, not just async review.
|
||||
|
||||
---
|
||||
|
||||
## 12. Collaboration Hooks
|
||||
|
||||
- **QR features**: Sync with Security before merging → permissions & privacy.
|
||||
- **New platform builds**: Demo in team meeting → confirm UX differences.
|
||||
- **Critical ADRs**: Present in guild or architecture review.
|
||||
|
||||
---
|
||||
|
||||
# Self-Check
|
||||
|
||||
- [ ] Does this feature implement a shared interface?
|
||||
- [ ] Are fallbacks + errors handled gracefully?
|
||||
- [ ] Have relevant ADRs been updated/linked?
|
||||
- [ ] Did I add competence hooks or prompts for the team?
|
||||
- [ ] Was human interaction (sync/review/demo) scheduled?
|
||||
316
.cursor/rules/app/timesafari.mdc
Normal file
316
.cursor/rules/app/timesafari.mdc
Normal file
@@ -0,0 +1,316 @@
|
||||
---
|
||||
description:
|
||||
globs:
|
||||
alwaysApply: true
|
||||
---
|
||||
# Time Safari Context
|
||||
|
||||
## Project Overview
|
||||
|
||||
Time Safari is an application designed to foster community building through gifts,
|
||||
gratitude, and collaborative projects. The app should make it extremely easy and
|
||||
intuitive for users of any age and capability to recognize contributions, build
|
||||
trust networks, and organize collective action. It is built on services that
|
||||
preserve privacy and data sovereignty.
|
||||
|
||||
The ultimate goals of Time Safari are two-fold:
|
||||
|
||||
1. **Connect** Make it easy, rewarding, and non-threatening for people to
|
||||
connect with others who have similar interests, and to initiate activities
|
||||
together. This helps people accomplish and learn from other individuals in
|
||||
less-structured environments; moreover, it helps them discover who they want
|
||||
to continue to support and with whom they want to maintain relationships.
|
||||
|
||||
2. **Reveal** Widely advertise the great support and rewards that are being
|
||||
given and accepted freely, especially non-monetary ones. Using visuals and text,
|
||||
display the kind of impact that gifts are making in the lives of others. Also
|
||||
show useful and engaging reports of project statistics and personal accomplishments.
|
||||
|
||||
|
||||
## Core Approaches
|
||||
|
||||
Time Safari should help everyday users build meaningful connections and organize
|
||||
collective efforts by:
|
||||
|
||||
1. **Recognizing Contributions**: Creating permanent, verifiable records of gifts
|
||||
and contributions people give to each other and their communities.
|
||||
|
||||
2. **Facilitating Collaboration**: Making it ridiculously easy for people to ask
|
||||
for or propose help on projects and interests that matter to them.
|
||||
|
||||
3. **Building Trust Networks**: Enabling users to maintain their network and activity
|
||||
visibility. Developing reputation through verified contributions and references,
|
||||
which can be selectively shown to others outside the network.
|
||||
|
||||
4. **Preserving Privacy**: Ensuring personal identifiers are only shared with
|
||||
explicitly authorized contacts, allowing private individuals including children
|
||||
to participate safely.
|
||||
|
||||
5. **Engaging Content**: Displaying people's records in compelling stories, and
|
||||
highlighting those projects that are lifting people's lives long-term, both in
|
||||
physical support and in emotional-spiritual-creative thriving.
|
||||
|
||||
|
||||
## Technical Foundation
|
||||
|
||||
This application is built on a privacy-preserving claims architecture (via
|
||||
endorser.ch) with these key characteristics:
|
||||
|
||||
- **Decentralized Identifiers (DIDs)**: User identities are based on public/private
|
||||
key pairs stored on their devices
|
||||
- **Cryptographic Verification**: All claims and confirmations are
|
||||
cryptographically signed
|
||||
- **User-Controlled Visibility**: Users explicitly control who can see their
|
||||
identifiers and data
|
||||
- **Merkle-Chained Claims**: Claims are cryptographically chained for verification
|
||||
and integrity
|
||||
- **Native and Web App**: Works on Capacitor (iOS, Android), Desktop (Electron
|
||||
and CEFPython), and web browsers
|
||||
|
||||
## User Journey
|
||||
|
||||
The typical progression of usage follows these stages:
|
||||
|
||||
1. **Gratitude & Recognition**: Users begin by expressing and recording gratitude
|
||||
for gifts received, building a foundation of acknowledgment.
|
||||
|
||||
2. **Project Proposals**: Users propose projects and ideas, reaching out to connect
|
||||
with others who share similar interests.
|
||||
|
||||
3. **Action Triggers**: Offers of help serve as triggers and motivations to execute
|
||||
proposed projects, moving from ideas to action.
|
||||
|
||||
## Context for LLM Development
|
||||
|
||||
When developing new functionality for Time Safari, consider these design principles:
|
||||
|
||||
1. **Accessibility First**: Features should be usable by non-technical users with
|
||||
minimal learning curve.
|
||||
|
||||
2. **Privacy by Design**: All features must respect user privacy and data sovereignty.
|
||||
|
||||
3. **Progressive Enhancement**: Core functionality should work across all devices,
|
||||
with richer experiences where supported.
|
||||
|
||||
4. **Voluntary Collaboration**: The system should enable but never coerce participation.
|
||||
|
||||
5. **Trust Building**: Features should help build verifiable trust between users.
|
||||
|
||||
6. **Network Effects**: Consider how features scale as more users join the platform.
|
||||
|
||||
7. **Low Resource Requirements**: The system should be lightweight enough to run
|
||||
on inexpensive devices users already own.
|
||||
|
||||
## Use Cases to Support
|
||||
|
||||
LLM development should focus on enhancing these key use cases:
|
||||
|
||||
1. **Community Building**: Tools that help people find others with shared
|
||||
interests and values.
|
||||
|
||||
2. **Project Coordination**: Features that make it easy to propose collaborative
|
||||
projects and to submit suggestions and offers to existing ones.
|
||||
|
||||
3. **Reputation Building**: Methods for users to showcase their contributions
|
||||
and reliability, in contexts where they explicitly reveal that information.
|
||||
|
||||
4. **Governance Experimentation**: Features that facilitate decision-making and
|
||||
collective governance.
|
||||
|
||||
## Constraints
|
||||
|
||||
When developing new features, be mindful of these constraints:
|
||||
|
||||
1. **Privacy Preservation**: User identifiers must remain private except when
|
||||
explicitly shared.
|
||||
|
||||
2. **Platform Limitations**: Features must work within the constraints of the target
|
||||
app platforms, while aiming to leverage the best platform technology available.
|
||||
|
||||
3. **Endorser API Limitations**: Backend features are constrained by the endorser.ch
|
||||
API capabilities.
|
||||
|
||||
4. **Performance on Low-End Devices**: The application should remain performant
|
||||
on older/simpler devices.
|
||||
|
||||
5. **Offline-First When Possible**: Key functionality should work offline when feasible.
|
||||
|
||||
## Project Technologies
|
||||
|
||||
- Typescript using ES6 classes using vue-facing-decorator
|
||||
- TailwindCSS
|
||||
- Vite Build Tool
|
||||
- Playwright E2E testing
|
||||
- IndexDB
|
||||
- Camera, Image uploads, QR Code reader, ...
|
||||
|
||||
## Mobile Features
|
||||
|
||||
- Deep Linking
|
||||
- Local Notifications via a custom Capacitor plugin
|
||||
|
||||
## Project Architecture
|
||||
|
||||
- The application must work on web browser, PWA (Progressive Web Application),
|
||||
desktop via Electron, and mobile via Capacitor
|
||||
- Building for each platform is managed via Vite
|
||||
|
||||
## Core Development Principles
|
||||
|
||||
### DRY development
|
||||
|
||||
- **Code Reuse**
|
||||
- Extract common functionality into utility functions
|
||||
- Create reusable components for UI patterns
|
||||
- Implement service classes for shared business logic
|
||||
- Use mixins for cross-cutting concerns
|
||||
- Leverage TypeScript interfaces for shared type definitions
|
||||
|
||||
- **Component Patterns**
|
||||
- Create base components for common UI elements
|
||||
- Implement higher-order components for shared behavior
|
||||
- Use slot patterns for flexible component composition
|
||||
- Create composable services for business logic
|
||||
- Implement factory patterns for component creation
|
||||
|
||||
- **State Management**
|
||||
- Centralize state in Pinia stores
|
||||
- Use computed properties for derived state
|
||||
- Implement shared state selectors
|
||||
- Create reusable state mutations
|
||||
- Use action creators for common operations
|
||||
|
||||
- **Error Handling**
|
||||
- Implement centralized error handling
|
||||
- Create reusable error components
|
||||
- Use error boundary components
|
||||
- Implement consistent error logging
|
||||
- Create error type definitions
|
||||
|
||||
- **Type Definitions**
|
||||
- Create shared interfaces for common data structures
|
||||
- Use type aliases for complex types
|
||||
- Implement generic types for reusable components
|
||||
- Create utility types for common patterns
|
||||
- Use discriminated unions for state management
|
||||
|
||||
- **API Integration**
|
||||
- Create reusable API client classes
|
||||
- Implement request/response interceptors
|
||||
- Use consistent error handling patterns
|
||||
- Create type-safe API endpoints
|
||||
- Implement caching strategies
|
||||
|
||||
- **Platform Services**
|
||||
- Abstract platform-specific code behind interfaces
|
||||
- Create platform-agnostic service layers
|
||||
- Implement feature detection
|
||||
- Use dependency injection for services
|
||||
- Create service factories
|
||||
|
||||
- **Testing**
|
||||
- Create reusable test utilities
|
||||
- Implement test factories
|
||||
- Use shared test configurations
|
||||
- Create reusable test helpers
|
||||
- Implement consistent test patterns
|
||||
- F.I.R.S.T. (for Unit Tests)
|
||||
F – Fast
|
||||
I – Independent
|
||||
R – Repeatable
|
||||
S – Self-validating
|
||||
T – Timely
|
||||
|
||||
### SOLID Principles
|
||||
|
||||
- **Single Responsibility**: Each class/component should have only one reason to
|
||||
change
|
||||
- Components should focus on one specific feature (e.g., QR scanning, DID management)
|
||||
- Services should handle one type of functionality (e.g., platform services,
|
||||
crypto services)
|
||||
- Utilities should provide focused helper functions
|
||||
|
||||
- **Open/Closed**: Software entities should be open for extension but closed for
|
||||
modification
|
||||
- Use interfaces for service definitions
|
||||
- Implement plugin architecture for platform-specific features
|
||||
- Allow component behavior extension through props and events
|
||||
|
||||
- **Liskov Substitution**: Objects should be replaceable with their subtypes
|
||||
- Platform services should work consistently across web/mobile
|
||||
- Authentication providers should be interchangeable
|
||||
- Storage implementations should be swappable
|
||||
|
||||
- **Interface Segregation**: Clients shouldn't depend on interfaces they don't use
|
||||
- Break down large service interfaces into smaller, focused ones
|
||||
- Component props should be minimal and purposeful
|
||||
- Event emissions should be specific and targeted
|
||||
|
||||
- **Dependency Inversion**: High-level modules shouldn't depend on low-level modules
|
||||
- Use dependency injection for services
|
||||
- Abstract platform-specific code behind interfaces
|
||||
- Implement factory patterns for component creation
|
||||
|
||||
### Law of Demeter
|
||||
|
||||
- Components should only communicate with immediate dependencies
|
||||
- Avoid chaining method calls (e.g., `this.service.getUser().getProfile().getName()`)
|
||||
- Use mediator patterns for complex component interactions
|
||||
- Implement facade patterns for subsystem access
|
||||
- Keep component communication through defined events and props
|
||||
|
||||
### Composition over Inheritance
|
||||
|
||||
- Prefer building components through composition
|
||||
- Use mixins for shared functionality
|
||||
- Implement feature toggles through props
|
||||
- Create higher-order components for common patterns
|
||||
- Use service composition for complex features
|
||||
|
||||
### Interface Segregation
|
||||
|
||||
- Define clear interfaces for services
|
||||
- Keep component APIs minimal and focused
|
||||
- Split large interfaces into smaller, specific ones
|
||||
- Use TypeScript interfaces for type definitions
|
||||
- Implement role-based interfaces for different use cases
|
||||
|
||||
### Fail Fast
|
||||
|
||||
- Validate inputs early in the process
|
||||
- Use TypeScript strict mode
|
||||
- Implement comprehensive error handling
|
||||
- Add runtime checks for critical operations
|
||||
- Use assertions for development-time validation
|
||||
|
||||
### Principle of Least Astonishment
|
||||
|
||||
- Follow Vue.js conventions consistently
|
||||
- Use familiar naming patterns
|
||||
- Implement predictable component behaviors
|
||||
- Maintain consistent error handling
|
||||
- Keep UI interactions intuitive
|
||||
|
||||
### Information Hiding
|
||||
|
||||
- Encapsulate implementation details
|
||||
- Use private class members
|
||||
- Implement proper access modifiers
|
||||
- Hide complex logic behind simple interfaces
|
||||
- Use TypeScript's access modifiers effectively
|
||||
|
||||
### Single Source of Truth
|
||||
|
||||
- Use Pinia for state management
|
||||
- Maintain one source for user data
|
||||
- Centralize configuration management
|
||||
- Use computed properties for derived state
|
||||
- Implement proper state synchronization
|
||||
|
||||
### Principle of Least Privilege
|
||||
|
||||
- Implement proper access control
|
||||
- Use minimal required permissions
|
||||
- Follow privacy-by-design principles
|
||||
- Restrict component access to necessary data
|
||||
- Implement proper authentication/authorization
|
||||
Reference in New Issue
Block a user