mirror of
https://github.com/DocNR/POWR.git
synced 2025-05-25 03:12:08 +00:00
documentation update
This commit is contained in:
parent
87cdf3fc1c
commit
c771af1b08
4
app.json
4
app.json
@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"expo": {
|
"expo": {
|
||||||
"name": "rnr-test",
|
"name": "powr",
|
||||||
"slug": "rnr-test",
|
"slug": "powr",
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"orientation": "portrait",
|
"orientation": "portrait",
|
||||||
"icon": "./assets/images/icon.png",
|
"icon": "./assets/images/icon.png",
|
||||||
|
224
docs/design/database_architecture.md
Normal file
224
docs/design/database_architecture.md
Normal file
@ -0,0 +1,224 @@
|
|||||||
|
# POWR Database Architecture Diagrams
|
||||||
|
|
||||||
|
## 1. Entity Relationship Diagram
|
||||||
|
|
||||||
|
This diagram shows the core database structure and relationships between tables. The design supports both raw Nostr event storage and processed data for efficient querying.
|
||||||
|
|
||||||
|
Key Features:
|
||||||
|
- Raw Nostr event storage in `nostr_events`
|
||||||
|
- Processed exercise data in `exercise_definitions`
|
||||||
|
- Dependency tracking in `incomplete_templates`
|
||||||
|
- Efficient tag indexing in `event_tags`
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
erDiagram
|
||||||
|
nostr_events ||--o{ event_tags : contains
|
||||||
|
nostr_events ||--o| exercise_definitions : processes
|
||||||
|
nostr_events ||--o| incomplete_templates : tracks
|
||||||
|
nostr_events {
|
||||||
|
string id PK
|
||||||
|
string pubkey
|
||||||
|
number kind
|
||||||
|
string raw_event
|
||||||
|
number created_at
|
||||||
|
number received_at
|
||||||
|
}
|
||||||
|
event_tags {
|
||||||
|
string event_id FK
|
||||||
|
string name
|
||||||
|
string value
|
||||||
|
number index
|
||||||
|
}
|
||||||
|
exercise_definitions {
|
||||||
|
string event_id FK
|
||||||
|
string title
|
||||||
|
string equipment
|
||||||
|
string format
|
||||||
|
string format_units
|
||||||
|
}
|
||||||
|
incomplete_templates {
|
||||||
|
string template_id FK
|
||||||
|
number missing_exercise_count
|
||||||
|
string missing_exercises
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. Event Processing Flow
|
||||||
|
|
||||||
|
This diagram illustrates how different types of Nostr events (Exercise Definitions, Workout Templates, and Workout Records) are processed, validated, and stored.
|
||||||
|
|
||||||
|
Key Features:
|
||||||
|
- Event type differentiation
|
||||||
|
- Validation process
|
||||||
|
- Dependency checking
|
||||||
|
- Storage paths for complete/incomplete data
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
subgraph Input
|
||||||
|
A[New Nostr Event] --> B{Event Type}
|
||||||
|
end
|
||||||
|
|
||||||
|
B -->|kind 33401| C[Exercise Definition]
|
||||||
|
B -->|kind 33402| D[Workout Template]
|
||||||
|
B -->|kind 33403| E[Workout Record]
|
||||||
|
|
||||||
|
subgraph Processing
|
||||||
|
C --> F[Validate Event]
|
||||||
|
D --> F
|
||||||
|
E --> F
|
||||||
|
|
||||||
|
F --> G{Valid?}
|
||||||
|
G -->|No| H[Reject Event]
|
||||||
|
G -->|Yes| I[Store Raw Event]
|
||||||
|
|
||||||
|
I --> J[Process Event]
|
||||||
|
J --> K{Dependencies?}
|
||||||
|
|
||||||
|
K -->|Missing| L[Store as Incomplete]
|
||||||
|
K -->|Complete| M[Store Processed Data]
|
||||||
|
|
||||||
|
L --> N[Queue Missing Events]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Storage
|
||||||
|
M --> O[(NostrEvents)]
|
||||||
|
M --> P[(ProcessedData)]
|
||||||
|
L --> Q[(IncompleteQueue)]
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Query and Cache Flow
|
||||||
|
|
||||||
|
This sequence diagram shows how data is retrieved, utilizing the LRU cache for performance and handling template dependencies.
|
||||||
|
|
||||||
|
Key Features:
|
||||||
|
- Cache hit/miss handling
|
||||||
|
- Template dependency resolution
|
||||||
|
- Efficient data retrieval paths
|
||||||
|
- Incomplete template handling
|
||||||
|
- Solid line with arrow (->>) means "makes a request to"
|
||||||
|
- Dashed line (-->) means "returns data to"
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant C as Client
|
||||||
|
participant Cache as LRU Cache
|
||||||
|
participant DB as SQLite
|
||||||
|
participant Q as Query Builder
|
||||||
|
|
||||||
|
C->>Q: Client asks Query Builder for templates
|
||||||
|
Q->>Cache: Query Builder first checks if data is in cache
|
||||||
|
|
||||||
|
alt Cache Hit
|
||||||
|
Cache-->>C: Quickly Returns Data found in Cache
|
||||||
|
else Cache Miss: Data not in cache, must query DB
|
||||||
|
Q->>DB: Query Database
|
||||||
|
DB-->>Q: Raw Results
|
||||||
|
Q->>Q: Process Raw Data
|
||||||
|
Q->>Cache: Store in Cache
|
||||||
|
Q-->>C: Return Results
|
||||||
|
end
|
||||||
|
|
||||||
|
Note over C,DB: Template Dependency Resolution
|
||||||
|
|
||||||
|
C->>Q: Template Request
|
||||||
|
Q->>DB: Fetch Template
|
||||||
|
DB-->>Q: Template Data
|
||||||
|
Q->>DB: Check Dependencies
|
||||||
|
|
||||||
|
alt Missing Dependencies
|
||||||
|
DB-->>Q: Missing Exercises
|
||||||
|
Q->>C: Return Incomplete
|
||||||
|
else Complete
|
||||||
|
DB-->>Q: All Dependencies
|
||||||
|
Q->>C: Return Complete Template
|
||||||
|
end
|
||||||
|
```
|
||||||
|
The second part shows template dependency resolution:
|
||||||
|
- Template request process
|
||||||
|
- Dependency checking
|
||||||
|
- Different responses based on whether all exercises exist
|
||||||
|
The key learning points:
|
||||||
|
- Cache is checked first to improve performance
|
||||||
|
- Database is only queried if necessary
|
||||||
|
- Results are cached for future use
|
||||||
|
- Dependencies are verified before returning complete templates
|
||||||
|
|
||||||
|
## 4. Component Architecture
|
||||||
|
|
||||||
|
This diagram shows the overall application architecture, including service layers and future Nostr integration points.
|
||||||
|
|
||||||
|
Key Features:
|
||||||
|
- Clear layer separation
|
||||||
|
- Service interactions
|
||||||
|
- Cache management
|
||||||
|
- Future Nostr integration points
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TB
|
||||||
|
subgraph UI Layer
|
||||||
|
A[Library Screen]
|
||||||
|
B[Exercise Form]
|
||||||
|
C[Template Form]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Service Layer
|
||||||
|
D[Library Service]
|
||||||
|
E[Event Processor]
|
||||||
|
F[Cache Manager]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Data Layer
|
||||||
|
G[(SQLite)]
|
||||||
|
H[Query Builder]
|
||||||
|
I[Event Validators]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Future Nostr
|
||||||
|
J[Relay Manager]
|
||||||
|
K[Event Publisher]
|
||||||
|
L[Sync Manager]
|
||||||
|
end
|
||||||
|
|
||||||
|
A --> D
|
||||||
|
B --> D
|
||||||
|
C --> D
|
||||||
|
|
||||||
|
D --> E
|
||||||
|
D --> F
|
||||||
|
|
||||||
|
E --> I
|
||||||
|
E --> G
|
||||||
|
|
||||||
|
F --> G
|
||||||
|
F --> H
|
||||||
|
|
||||||
|
H --> G
|
||||||
|
|
||||||
|
D -.-> J
|
||||||
|
D -.-> K
|
||||||
|
D -.-> L
|
||||||
|
```
|
||||||
|
|
||||||
|
## Implementation Notes
|
||||||
|
|
||||||
|
These diagrams represent the core architecture of POWR's database implementation. Key considerations:
|
||||||
|
|
||||||
|
1. **Data Flow**
|
||||||
|
- All Nostr events are stored in raw form
|
||||||
|
- Processed data is stored separately for efficiency
|
||||||
|
- Cache layer improves read performance
|
||||||
|
- Dependency tracking ensures data integrity
|
||||||
|
|
||||||
|
2. **Scalability**
|
||||||
|
- Modular design allows for future expansion
|
||||||
|
- Clear separation of concerns
|
||||||
|
- Efficient query patterns
|
||||||
|
- Prepared for Nostr integration
|
||||||
|
|
||||||
|
3. **Performance**
|
||||||
|
- LRU caching for frequent queries
|
||||||
|
- Optimized indexes for common operations
|
||||||
|
- Efficient dependency resolution
|
||||||
|
- Batch processing capability
|
216
docs/design/database_implementation.md
Normal file
216
docs/design/database_implementation.md
Normal file
@ -0,0 +1,216 @@
|
|||||||
|
# POWR Database Implementation Design Document
|
||||||
|
|
||||||
|
## Problem Statement
|
||||||
|
Implement a SQLite database that supports local-first fitness tracking while enabling seamless Nostr protocol integration. The system must handle exercise definitions (NIP-33401), workout templates (NIP-33402), and workout records (NIP-33403) while managing event dependencies, caching, and efficient querying.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
### Functional Requirements
|
||||||
|
- Store and process Nostr events (33401, 33402, 33403)
|
||||||
|
- Handle incomplete workout templates with missing exercise references
|
||||||
|
- Support both local and Nostr-sourced content
|
||||||
|
- Enable efficient content querying and filtering
|
||||||
|
- Track template completeness and dependencies
|
||||||
|
- Manage event replacements and updates
|
||||||
|
|
||||||
|
### Non-Functional Requirements
|
||||||
|
- Query response time < 100ms
|
||||||
|
- Support offline-first operations
|
||||||
|
- Handle concurrent write operations safely
|
||||||
|
- Efficient storage for device constraints
|
||||||
|
- Maintain data integrity with event dependencies
|
||||||
|
|
||||||
|
## Design Decisions
|
||||||
|
|
||||||
|
### 1. Event Storage Strategy
|
||||||
|
Store both raw Nostr events and processed data:
|
||||||
|
- Raw events for perfect relay replication
|
||||||
|
- Processed data for efficient querying
|
||||||
|
- Separate incomplete template tracking
|
||||||
|
- Tag indexing for fast lookups
|
||||||
|
|
||||||
|
Rationale:
|
||||||
|
- Maintains Nostr protocol compliance
|
||||||
|
- Enables efficient local operations
|
||||||
|
- Supports dependency tracking
|
||||||
|
- Facilitates sync operations
|
||||||
|
|
||||||
|
### 2. Dependency Management
|
||||||
|
Track missing exercise references:
|
||||||
|
- Store incomplete templates
|
||||||
|
- Track missing dependencies
|
||||||
|
- Enable background fetching
|
||||||
|
- Allow filtering by completeness
|
||||||
|
|
||||||
|
Rationale:
|
||||||
|
- Better user experience
|
||||||
|
- Data integrity
|
||||||
|
- Eventual consistency
|
||||||
|
- Clear status tracking
|
||||||
|
|
||||||
|
## Technical Design
|
||||||
|
|
||||||
|
### Core Schema
|
||||||
|
```typescript
|
||||||
|
interface DatabaseSchema {
|
||||||
|
// Raw Nostr event storage
|
||||||
|
nostr_events: {
|
||||||
|
id: string; // 32-bytes hex
|
||||||
|
pubkey: string; // 32-bytes hex
|
||||||
|
kind: number; // 33401 | 33402 | 33403
|
||||||
|
raw_event: string; // Full JSON event
|
||||||
|
created_at: number; // Unix timestamp
|
||||||
|
received_at: number; // Local timestamp
|
||||||
|
};
|
||||||
|
|
||||||
|
// Processed exercise definitions
|
||||||
|
exercise_definitions: {
|
||||||
|
event_id: string; // Reference to nostr_events
|
||||||
|
title: string;
|
||||||
|
equipment: string;
|
||||||
|
format: string; // JSON stringified
|
||||||
|
format_units: string; // JSON stringified
|
||||||
|
};
|
||||||
|
|
||||||
|
// Template dependency tracking
|
||||||
|
incomplete_templates: {
|
||||||
|
template_id: string; // Reference to nostr_events
|
||||||
|
missing_exercise_count: number;
|
||||||
|
missing_exercises: string; // JSON stringified
|
||||||
|
};
|
||||||
|
|
||||||
|
// Tag indexing
|
||||||
|
event_tags: {
|
||||||
|
event_id: string; // Reference to nostr_events
|
||||||
|
name: string; // Tag name
|
||||||
|
value: string; // Tag value
|
||||||
|
index: number; // Position in tag array
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Event Validators
|
||||||
|
```typescript
|
||||||
|
interface EventValidator {
|
||||||
|
validateEvent(event: NostrEvent): ValidationResult;
|
||||||
|
processEvent(event: NostrEvent): ProcessedEvent;
|
||||||
|
}
|
||||||
|
|
||||||
|
class ExerciseDefinitionValidator implements EventValidator {
|
||||||
|
// Implementation for kind 33401
|
||||||
|
}
|
||||||
|
|
||||||
|
class WorkoutTemplateValidator implements EventValidator {
|
||||||
|
// Implementation for kind 33402
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Implementation Plan
|
||||||
|
|
||||||
|
### Phase 1: Core Event Handling
|
||||||
|
1. Basic schema implementation
|
||||||
|
2. Event validation and processing
|
||||||
|
3. Tag indexing system
|
||||||
|
4. Basic CRUD operations
|
||||||
|
|
||||||
|
### Phase 2: Template Dependencies
|
||||||
|
1. Incomplete template tracking
|
||||||
|
2. Missing exercise handling
|
||||||
|
3. Background fetching system
|
||||||
|
4. Template status management
|
||||||
|
|
||||||
|
### Phase 3: Query Optimization
|
||||||
|
1. Implement efficient indexes
|
||||||
|
2. Query caching system
|
||||||
|
3. Common query patterns
|
||||||
|
4. Performance monitoring
|
||||||
|
|
||||||
|
## Testing Strategy
|
||||||
|
|
||||||
|
### Unit Tests
|
||||||
|
- Event validation
|
||||||
|
- Data processing
|
||||||
|
- CRUD operations
|
||||||
|
- Tag indexing
|
||||||
|
|
||||||
|
### Integration Tests
|
||||||
|
- Template dependency handling
|
||||||
|
- Event synchronization
|
||||||
|
- Cache operations
|
||||||
|
- Query performance
|
||||||
|
|
||||||
|
### Performance Tests
|
||||||
|
- Query response times
|
||||||
|
- Write operation latency
|
||||||
|
- Cache efficiency
|
||||||
|
- Storage utilization
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
- Event signature validation
|
||||||
|
- Input sanitization
|
||||||
|
- Access control
|
||||||
|
- Data integrity
|
||||||
|
|
||||||
|
## Future Considerations
|
||||||
|
|
||||||
|
### Potential Enhancements
|
||||||
|
- Advanced caching strategies
|
||||||
|
- Relay management
|
||||||
|
- Batch operations
|
||||||
|
- Compression options
|
||||||
|
|
||||||
|
### Known Limitations
|
||||||
|
- SQLite concurrent access
|
||||||
|
- Dependency completeness
|
||||||
|
- Cache memory constraints
|
||||||
|
- Initial sync performance
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
### Runtime Dependencies
|
||||||
|
- expo-sqlite
|
||||||
|
- @react-native-async-storage/async-storage
|
||||||
|
|
||||||
|
### Development Dependencies
|
||||||
|
- Jest for testing
|
||||||
|
- SQLite tooling
|
||||||
|
- TypeScript
|
||||||
|
|
||||||
|
## Query Examples
|
||||||
|
|
||||||
|
### Template Queries
|
||||||
|
```typescript
|
||||||
|
// Get templates by author
|
||||||
|
async getTemplatesByPubkey(
|
||||||
|
pubkey: string,
|
||||||
|
options: {
|
||||||
|
includeIncomplete?: boolean;
|
||||||
|
limit?: number;
|
||||||
|
since?: number;
|
||||||
|
}
|
||||||
|
): Promise<ProcessedTemplate[]>
|
||||||
|
|
||||||
|
// Get template with exercises
|
||||||
|
async getTemplateWithExercises(
|
||||||
|
templateId: string
|
||||||
|
): Promise<CompleteTemplate>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Exercise Queries
|
||||||
|
```typescript
|
||||||
|
// Search exercises
|
||||||
|
async searchExercises(
|
||||||
|
params: SearchParams
|
||||||
|
): Promise<ProcessedExerciseDefinition[]>
|
||||||
|
|
||||||
|
// Get exercise history
|
||||||
|
async getExerciseHistory(
|
||||||
|
exerciseId: string
|
||||||
|
): Promise<ExerciseHistory[]>
|
||||||
|
```
|
||||||
|
|
||||||
|
## References
|
||||||
|
- NDK SQLite Implementation
|
||||||
|
- Nostr NIP-01 Specification
|
||||||
|
- POWR Exercise NIP Draft
|
||||||
|
- POWR Library Tab PRD
|
195
docs/design/nostr-exercise-nip.md
Normal file
195
docs/design/nostr-exercise-nip.md
Normal file
@ -0,0 +1,195 @@
|
|||||||
|
# NIP-XX: Workout Events
|
||||||
|
|
||||||
|
`draft` `optional`
|
||||||
|
|
||||||
|
This specification defines workout events for fitness tracking. These workout events support both planning (templates) and recording (completed activities).
|
||||||
|
|
||||||
|
## Event Kinds
|
||||||
|
|
||||||
|
### Exercise Template (kind: 33401)
|
||||||
|
Defines reusable exercise definitions. These should remain public to enable discovery and sharing. The `content` field contains detailed form instructions and notes.
|
||||||
|
|
||||||
|
#### Required Tags
|
||||||
|
* `d` - UUID for template identification
|
||||||
|
* `title` - Exercise name
|
||||||
|
* `format` - Defines data structure for exercise tracking (possible parameters: `weight`, `reps`, `rpe`, `set_type`)
|
||||||
|
* `format_units` - Defines units for each parameter (possible formats: "kg", "count", "0-10", "warmup|normal|drop|failure")
|
||||||
|
* `equipment` - Equipment type (possible values: `barbell`, `dumbbell`, `bodyweight`, `machine`, `cardio`)
|
||||||
|
|
||||||
|
#### Optional Tags
|
||||||
|
* `difficulty` - Skill level (possible values: `beginner`, `intermediate`, `advanced`)
|
||||||
|
* `imeta` - Media metadata for form demonstrations following NIP-92 format
|
||||||
|
* `t` - Hashtags for categorization such as muscle group or body movement (possible values: `chest`, `legs`, `push`, `pull`)
|
||||||
|
|
||||||
|
### Workout Template (kind: 33402)
|
||||||
|
Defines a complete workout plan. The `content` field contains workout notes and instructions. Workout templates can prescribe specific parameters while leaving others configurable by the user performing the workout.
|
||||||
|
|
||||||
|
#### Required Tags
|
||||||
|
* `d` - UUID for template identification
|
||||||
|
* `title` - Workout name
|
||||||
|
* `type` - Type of workout (possible values: `strength`, `circuit`, `emom`, `amrap`)
|
||||||
|
* `exercise` - Exercise reference and prescription. Format: ["exercise", "kind:pubkey:d-tag", "relay-url", ...parameters matching exercise template format]
|
||||||
|
|
||||||
|
#### Optional Tags
|
||||||
|
* `rounds` - Number of rounds for repeating formats
|
||||||
|
* `duration` - Total workout duration in seconds
|
||||||
|
* `interval` - Duration of each exercise portion in seconds (for timed workouts)
|
||||||
|
* `rest_between_rounds` - Rest time between rounds in seconds
|
||||||
|
* `t` - Hashtags for categorization
|
||||||
|
|
||||||
|
### Workout Record (kind: 33403)
|
||||||
|
Records a completed workout session. The `content` field contains notes about the workout.
|
||||||
|
|
||||||
|
#### Required Tags
|
||||||
|
* `d` - UUID for record identification
|
||||||
|
* `title` - Workout name
|
||||||
|
* `type` - Type of workout (possible values: `strength`, `circuit`, `emom`, `amrap`)
|
||||||
|
* `exercise` - Exercise reference and completion data. Format: ["exercise", "kind:pubkey:d-tag", "relay-url", ...parameters matching exercise template format]
|
||||||
|
* `start` - Unix timestamp in seconds for workout start
|
||||||
|
* `end` - Unix timestamp in seconds for workout end
|
||||||
|
* `completed` - Boolean indicating if workout was completed as planned
|
||||||
|
|
||||||
|
#### Optional Tags
|
||||||
|
* `rounds_completed` - Number of rounds completed
|
||||||
|
* `interval` - Duration of each exercise portion in seconds (for timed workouts)
|
||||||
|
* `pr` - Personal Record achieved during workout. Format: "kind:pubkey:d-tag,metric,value". Used to track when a user achieves their best performance for a given exercise and metric (e.g., heaviest weight lifted, most reps completed, fastest time)
|
||||||
|
* `t` - Hashtags for categorization
|
||||||
|
|
||||||
|
## Exercise Parameters
|
||||||
|
|
||||||
|
### Standard Parameters and Units
|
||||||
|
* `weight` - Load in kilograms (kg). Empty string for bodyweight exercises, negative values for assisted exercises
|
||||||
|
* `reps` - Number of repetitions (count)
|
||||||
|
* `rpe` - Rate of Perceived Exertion (0-10):
|
||||||
|
- RPE 10: Could not do any more reps, technical failure
|
||||||
|
- RPE 9: Could maybe do 1 more rep
|
||||||
|
- RPE 8: Could definitely do 1 more rep, maybe 2
|
||||||
|
- RPE 7: Could do 2-3 more reps
|
||||||
|
* `duration` - Time in seconds
|
||||||
|
* `set_type` - Set classification (possible values: `warmup`, `normal`, `drop`, `failure`)
|
||||||
|
|
||||||
|
Additional parameters can be defined in exercise templates in the `format_units` tag as needed for specific activities (e.g., distance, heartrate, intensity).
|
||||||
|
|
||||||
|
## Workout Types and Terminology
|
||||||
|
|
||||||
|
This specification provides examples of common workout structures but is not limited to these types. The format is extensible to support various training methodologies while maintaining consistent data structure.
|
||||||
|
|
||||||
|
### Common Workout Types
|
||||||
|
|
||||||
|
#### Strength
|
||||||
|
Traditional strength training focusing on sets and reps with defined weights. Typically includes warm-up sets, working sets, and may include techniques like drop sets or failure sets.
|
||||||
|
|
||||||
|
#### Circuit
|
||||||
|
Multiple exercises performed in sequence with minimal rest between exercises and defined rest periods between rounds. Focuses on maintaining work rate through prescribed exercises.
|
||||||
|
|
||||||
|
#### EMOM (Every Minute On the Minute)
|
||||||
|
Time-based workout where specific exercises are performed at the start of each minute. Rest time is whatever remains in the minute after completing prescribed work.
|
||||||
|
|
||||||
|
#### AMRAP (As Many Rounds/Reps As Possible)
|
||||||
|
Time-capped workout where the goal is to complete as many rounds or repetitions as possible of prescribed exercises while maintaining proper form.
|
||||||
|
|
||||||
|
## Set Types
|
||||||
|
|
||||||
|
### Normal Sets
|
||||||
|
Standard working sets that count toward volume and progress tracking.
|
||||||
|
|
||||||
|
### Warm-up Sets
|
||||||
|
Preparatory sets using submaximal weights. These sets are not counted in metrics or progress tracking.
|
||||||
|
|
||||||
|
### Drop Sets
|
||||||
|
Sets performed immediately after a working set with reduced weight. These are counted in volume calculations but tracked separately for progress analysis.
|
||||||
|
|
||||||
|
### Failure Sets
|
||||||
|
Sets where technical failure was reached before completing prescribed reps. These sets are counted in metrics but marked to indicate intensity/failure was reached.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
### Exercise Template
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"kind": 33401,
|
||||||
|
"content": "Stand with feet hip-width apart, barbell over midfoot. Hinge at hips, grip bar outside knees. Flatten back, brace core. Drive through floor, keeping bar close to legs.\n\nForm demonstration: https://powr.me/exercises/deadlift-demo.mp4",
|
||||||
|
"tags": [
|
||||||
|
["d", "bb-deadlift-template"],
|
||||||
|
["title", "Barbell Deadlift"],
|
||||||
|
["format", "weight", "reps", "rpe", "set_type"],
|
||||||
|
["format_units", "kg", "count", "0-10", "warmup|normal|drop|failure"],
|
||||||
|
["equipment", "barbell"],
|
||||||
|
["difficulty", "intermediate"],
|
||||||
|
["imeta",
|
||||||
|
"url https://powr.me/exercises/deadlift-demo.mp4",
|
||||||
|
"m video/mp4",
|
||||||
|
"dim 1920x1080",
|
||||||
|
"alt Demonstration of proper barbell deadlift form"
|
||||||
|
],
|
||||||
|
["t", "compound"],
|
||||||
|
["t", "legs"],
|
||||||
|
["t", "posterior"]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### EMOM Workout Template
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"kind": 33402,
|
||||||
|
"content": "20 minute EMOM alternating between squats and deadlifts every 30 seconds. Scale weight as needed to complete all reps within each interval.",
|
||||||
|
"tags": [
|
||||||
|
["d", "lower-body-emom-template"],
|
||||||
|
["title", "20min Squat/Deadlift EMOM"],
|
||||||
|
["type", "emom"],
|
||||||
|
["duration", "1200"],
|
||||||
|
["rounds", "20"],
|
||||||
|
["interval", "30"],
|
||||||
|
|
||||||
|
["exercise", "33401:9947f9659dd80c3682402b612f5447e28249997fb3709500c32a585eb0977340:bb-back-squat-template", "wss://powr.me", "", "5", "7", "normal"],
|
||||||
|
["exercise", "33401:9947f9659dd80c3682402b612f5447e28249997fb3709500c32a585eb0977340:bb-deadlift-template", "wss://powr.me", "", "4", "7", "normal"],
|
||||||
|
|
||||||
|
["t", "conditioning"],
|
||||||
|
["t", "legs"]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Circuit Workout Record
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"kind": 33403,
|
||||||
|
"content": "Completed first round as prescribed. Second round showed form deterioration on deadlifts.",
|
||||||
|
"tags": [
|
||||||
|
["d", "workout-20250128"],
|
||||||
|
["title", "Leg Circuit"],
|
||||||
|
["type", "circuit"],
|
||||||
|
["rounds_completed", "1.5"],
|
||||||
|
["start", "1706454000"],
|
||||||
|
["end", "1706455800"],
|
||||||
|
|
||||||
|
// Round 1 - Completed as prescribed
|
||||||
|
["exercise", "33401:9947f9659dd80c3682402b612f5447e28249997fb3709500c32a585eb0977340:bb-back-squat-template", "wss://powr.me", "80", "12", "7", "normal"],
|
||||||
|
["exercise", "33401:9947f9659dd80c3682402b612f5447e28249997fb3709500c32a585eb0977340:bb-deadlift-template", "wss://powr.me", "100", "10", "7", "normal"],
|
||||||
|
|
||||||
|
// Round 2 - Failed on deadlifts
|
||||||
|
["exercise", "33401:9947f9659dd80c3682402b612f5447e28249997fb3709500c32a585eb0977340:bb-back-squat-template", "wss://powr.me", "80", "12", "8", "normal"],
|
||||||
|
["exercise", "33401:9947f9659dd80c3682402b612f5447e28249997fb3709500c32a585eb0977340:bb-deadlift-template", "wss://powr.me", "100", "4", "10", "failure"],
|
||||||
|
|
||||||
|
["completed", "false"],
|
||||||
|
["t", "legs"]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Implementation Guidelines
|
||||||
|
|
||||||
|
1. All workout records SHOULD include accurate start and end times
|
||||||
|
2. Templates MAY prescribe specific parameters while leaving others as empty strings for user input
|
||||||
|
3. Records MUST include actual values for all parameters defined in exercise format
|
||||||
|
4. Failed sets SHOULD be marked with `failure` set_type
|
||||||
|
5. Records SHOULD be marked as `false` for completed if prescribed work wasn't completed
|
||||||
|
6. PRs SHOULD only be tracked in workout records, not templates
|
||||||
|
7. Exercise references SHOULD use the format "kind:pubkey:d-tag" to ensure proper attribution and versioning
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
This NIP draws inspiration from:
|
||||||
|
- [NIP-01: Basic Protocol Flow Description](https://github.com/nostr-protocol/nips/blob/master/01.md)
|
||||||
|
- [NIP-92: Media Attachments](https://github.com/nostr-protocol/nips/blob/master/92.md#nip-92)
|
@ -1,137 +1,231 @@
|
|||||||
# [Feature Name] Design Document
|
# POWR Database Implementation PRD
|
||||||
|
|
||||||
## Problem Statement
|
## Problem Statement
|
||||||
[Concise description of the problem being solved]
|
POWR requires a robust SQLite database implementation that enables local-first fitness tracking while supporting future Nostr protocol integration. The database must efficiently handle exercise definitions (NIP-33401), workout templates (NIP-33402), and workout records (NIP-33403) while maintaining a clean separation between local storage needs and Nostr protocol compatibility.
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
### Functional Requirements
|
### Functional Requirements
|
||||||
- [List of must-have functionality]
|
- Store and process exercise definitions with complete metadata
|
||||||
- [User-facing features]
|
- Support workout template creation and management
|
||||||
- [Core capabilities]
|
- Track workout records and performance history
|
||||||
|
- Enable efficient content querying and filtering
|
||||||
|
- Handle both local and Nostr-sourced content seamlessly
|
||||||
|
- Support offline-first operations with sync capabilities
|
||||||
|
- Manage template dependencies and incomplete references
|
||||||
|
- Track exercise history and performance metrics
|
||||||
|
- Support batch operations and migrations
|
||||||
|
|
||||||
### Non-Functional Requirements
|
### Non-Functional Requirements
|
||||||
- Performance targets
|
- Query response time < 100ms for common operations
|
||||||
- Security requirements
|
- Support concurrent read/write operations safely
|
||||||
- Reliability goals
|
- Minimize memory usage through efficient caching
|
||||||
- Usability standards
|
- Maintain data integrity across sync operations
|
||||||
|
- Scale to handle 1000+ exercises and 100+ templates
|
||||||
|
- Support incremental sync with Nostr relays
|
||||||
|
- Ensure consistent performance on mobile devices
|
||||||
|
- Support automated testing and validation
|
||||||
|
|
||||||
## Design Decisions
|
## Design Decisions
|
||||||
|
|
||||||
### 1. [Major Decision Area]
|
### 1. Storage Architecture
|
||||||
[Description of approach chosen]
|
Use a dual storage approach with separate tables for raw events and processed data:
|
||||||
|
|
||||||
Rationale:
|
Rationale:
|
||||||
- [Key reason]
|
- Maintains perfect relay replication capability
|
||||||
- [Supporting factors]
|
- Enables efficient local querying
|
||||||
- [Trade-offs considered]
|
- Supports dependency tracking
|
||||||
|
- Facilitates future sync operations
|
||||||
|
- Allows for flexible schema evolution
|
||||||
|
|
||||||
### 2. [Major Decision Area]
|
### 2. Cache Management
|
||||||
[Description of approach chosen]
|
Implement an LRU cache system with configurable limits:
|
||||||
|
|
||||||
Rationale:
|
Rationale:
|
||||||
- [Key reason]
|
- Improves read performance for common queries
|
||||||
- [Supporting factors]
|
- Manages memory usage effectively
|
||||||
- [Trade-offs considered]
|
- Supports write buffering for batch operations
|
||||||
|
- Provides tunable performance controls
|
||||||
|
|
||||||
|
### 3. Schema Design
|
||||||
|
Use a normalized schema with proper constraints and indexing:
|
||||||
|
|
||||||
|
Rationale:
|
||||||
|
- Ensures data integrity
|
||||||
|
- Enables efficient querying
|
||||||
|
- Supports future extensions
|
||||||
|
- Maintains clear relationships
|
||||||
|
|
||||||
## Technical Design
|
## Technical Design
|
||||||
|
|
||||||
|
### Core Schema
|
||||||
|
```sql
|
||||||
|
-- Schema Version
|
||||||
|
CREATE TABLE schema_version (
|
||||||
|
version INTEGER PRIMARY KEY,
|
||||||
|
updated_at INTEGER NOT NULL
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Raw Events
|
||||||
|
CREATE TABLE nostr_events (
|
||||||
|
id TEXT PRIMARY KEY,
|
||||||
|
kind INTEGER NOT NULL,
|
||||||
|
pubkey TEXT NOT NULL,
|
||||||
|
created_at INTEGER NOT NULL,
|
||||||
|
content TEXT,
|
||||||
|
raw_event TEXT NOT NULL,
|
||||||
|
source TEXT DEFAULT 'local'
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Processed Exercises
|
||||||
|
CREATE TABLE exercise_definitions (
|
||||||
|
event_id TEXT PRIMARY KEY,
|
||||||
|
title TEXT NOT NULL,
|
||||||
|
type TEXT NOT NULL,
|
||||||
|
category TEXT NOT NULL,
|
||||||
|
equipment TEXT,
|
||||||
|
description TEXT,
|
||||||
|
format_json TEXT,
|
||||||
|
format_units_json TEXT,
|
||||||
|
FOREIGN KEY(event_id) REFERENCES nostr_events(id)
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Templates
|
||||||
|
CREATE TABLE workout_templates (
|
||||||
|
event_id TEXT PRIMARY KEY,
|
||||||
|
title TEXT NOT NULL,
|
||||||
|
type TEXT NOT NULL,
|
||||||
|
category TEXT NOT NULL,
|
||||||
|
description TEXT,
|
||||||
|
rounds INTEGER,
|
||||||
|
duration INTEGER,
|
||||||
|
interval_time INTEGER,
|
||||||
|
rest_between_rounds INTEGER,
|
||||||
|
created_at INTEGER NOT NULL,
|
||||||
|
FOREIGN KEY(event_id) REFERENCES nostr_events(id)
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
### Core Components
|
### Core Components
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
// Key interfaces/types
|
interface DbService {
|
||||||
interface ComponentName {
|
// Core database operations
|
||||||
// Critical fields
|
executeSql(sql: string, params?: any[]): Promise<SQLiteResult>;
|
||||||
|
withTransaction<T>(operation: () => Promise<T>): Promise<T>;
|
||||||
|
|
||||||
|
// Migration handling
|
||||||
|
getCurrentVersion(): Promise<number>;
|
||||||
|
migrate(targetVersion?: number): Promise<void>;
|
||||||
}
|
}
|
||||||
|
|
||||||
// Core functionality
|
interface CacheManager {
|
||||||
function mainOperation() {
|
// Cache configuration
|
||||||
// Key logic
|
maxExercises: number;
|
||||||
|
maxTemplates: number;
|
||||||
|
writeBufferSize: number;
|
||||||
|
|
||||||
|
// Cache operations
|
||||||
|
get<T>(key: string): Promise<T | undefined>;
|
||||||
|
set<T>(key: string, value: T): Promise<void>;
|
||||||
|
invalidate(key: string): Promise<void>;
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Integration Points
|
|
||||||
- [System interfaces]
|
|
||||||
- [External dependencies]
|
|
||||||
- [API definitions]
|
|
||||||
|
|
||||||
## Implementation Plan
|
## Implementation Plan
|
||||||
|
|
||||||
### Phase 1: [Initial Phase]
|
### Phase 1: Core Infrastructure (Week 1-2)
|
||||||
1. [Step 1]
|
1. Set up base schema and migrations
|
||||||
2. [Step 2]
|
2. Implement DbService class
|
||||||
3. [Step 3]
|
3. Add basic CRUD operations
|
||||||
|
4. Create test infrastructure
|
||||||
|
|
||||||
### Phase 2: [Next Phase]
|
### Phase 2: Cache Layer (Week 2-3)
|
||||||
1. [Step 1]
|
1. Implement CacheManager
|
||||||
2. [Step 2]
|
2. Add LRU caching
|
||||||
3. [Step 3]
|
3. Configure write buffering
|
||||||
|
4. Add cache invalidation
|
||||||
|
|
||||||
|
### Phase 3: Query Layer (Week 3-4)
|
||||||
|
1. Build query builders
|
||||||
|
2. Implement common queries
|
||||||
|
3. Add search functionality
|
||||||
|
4. Optimize performance
|
||||||
|
|
||||||
|
### Phase 4: Nostr Integration (Week 4-5)
|
||||||
|
1. Add event processing
|
||||||
|
2. Implement sync logic
|
||||||
|
3. Handle dependencies
|
||||||
|
4. Add relay management
|
||||||
|
|
||||||
## Testing Strategy
|
## Testing Strategy
|
||||||
|
|
||||||
### Unit Tests
|
### Unit Tests
|
||||||
- [Key test areas]
|
- Schema creation and migrations
|
||||||
- [Critical test cases]
|
- CRUD operations for all entities
|
||||||
- [Test tooling]
|
- Cache operations and invalidation
|
||||||
|
- Query builder functions
|
||||||
|
|
||||||
### Integration Tests
|
### Integration Tests
|
||||||
- [End-to-end scenarios]
|
- End-to-end workflow testing
|
||||||
- [Cross-component tests]
|
- Template dependency handling
|
||||||
- [Test environments]
|
- Sync operations
|
||||||
|
- Performance benchmarks
|
||||||
|
|
||||||
|
### Performance Tests
|
||||||
|
- Query response times
|
||||||
|
- Cache hit rates
|
||||||
|
- Write operation latency
|
||||||
|
- Memory usage patterns
|
||||||
|
|
||||||
## Observability
|
## Observability
|
||||||
|
|
||||||
### Logging
|
### Logging
|
||||||
- [Key log points]
|
- Schema migrations
|
||||||
- [Log levels]
|
- Cache operations
|
||||||
- [Critical events]
|
- Query performance
|
||||||
|
- Error conditions
|
||||||
|
|
||||||
### Metrics
|
### Metrics
|
||||||
- [Performance metrics]
|
- Query response times
|
||||||
- [Business metrics]
|
- Cache hit/miss rates
|
||||||
- [System health metrics]
|
- Database size
|
||||||
|
- Operation counts
|
||||||
|
|
||||||
## Future Considerations
|
## Future Considerations
|
||||||
|
|
||||||
### Potential Enhancements
|
### Potential Enhancements
|
||||||
- [Future feature ideas]
|
- Advanced caching strategies
|
||||||
- [Scalability improvements]
|
- Full-text search
|
||||||
- [Technical debt items]
|
- Data compression
|
||||||
|
- Cloud backup options
|
||||||
|
|
||||||
### Known Limitations
|
### Known Limitations
|
||||||
- [Current constraints]
|
- SQLite concurrent access
|
||||||
- [Technical restrictions]
|
- Initial sync performance
|
||||||
- [Scope boundaries]
|
- Cache memory constraints
|
||||||
|
- Platform-specific issues
|
||||||
|
|
||||||
## Dependencies
|
## Dependencies
|
||||||
|
|
||||||
### Runtime Dependencies
|
### Runtime Dependencies
|
||||||
- [External services]
|
- expo-sqlite
|
||||||
- [Libraries]
|
- @react-native-async-storage/async-storage
|
||||||
- [System requirements]
|
- NDK (future)
|
||||||
|
|
||||||
### Development Dependencies
|
### Development Dependencies
|
||||||
- [Build tools]
|
- Jest
|
||||||
- [Test frameworks]
|
- TypeScript
|
||||||
- [Development utilities]
|
- SQLite development tools
|
||||||
|
|
||||||
## Security Considerations
|
## Security Considerations
|
||||||
- [Security measures]
|
- Input validation
|
||||||
- [Privacy concerns]
|
- Query parameterization
|
||||||
- [Data protection]
|
- Event signature verification
|
||||||
|
- Access control
|
||||||
## Rollout Strategy
|
|
||||||
|
|
||||||
### Development Phase
|
|
||||||
1. [Development steps]
|
|
||||||
2. [Testing approach]
|
|
||||||
3. [Documentation needs]
|
|
||||||
|
|
||||||
### Production Deployment
|
|
||||||
1. [Deployment steps]
|
|
||||||
2. [Migration plan]
|
|
||||||
3. [Monitoring setup]
|
|
||||||
|
|
||||||
## References
|
## References
|
||||||
- [Related documents]
|
- NDK SQLite Implementation
|
||||||
- [External resources]
|
- Nostr NIP-01 Specification
|
||||||
- [Research materials]
|
- POWR Exercise NIP Draft
|
||||||
|
- React Native SQLite Documentation
|
4
package-lock.json
generated
4
package-lock.json
generated
@ -1,11 +1,11 @@
|
|||||||
{
|
{
|
||||||
"name": "rnr-test",
|
"name": "powr",
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"lockfileVersion": 3,
|
"lockfileVersion": 3,
|
||||||
"requires": true,
|
"requires": true,
|
||||||
"packages": {
|
"packages": {
|
||||||
"": {
|
"": {
|
||||||
"name": "rnr-test",
|
"name": "powr",
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"hasInstallScript": true,
|
"hasInstallScript": true,
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
|
@ -1,5 +1,5 @@
|
|||||||
{
|
{
|
||||||
"name": "rnr-test",
|
"name": "powr",
|
||||||
"main": "index.js",
|
"main": "index.js",
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
|
Loading…
x
Reference in New Issue
Block a user