mirror of
https://github.com/DocNR/POWR.git
synced 2025-04-23 01:01:27 +00:00
documentation update
This commit is contained in:
parent
87cdf3fc1c
commit
c771af1b08
4
app.json
4
app.json
@ -1,7 +1,7 @@
|
||||
{
|
||||
"expo": {
|
||||
"name": "rnr-test",
|
||||
"slug": "rnr-test",
|
||||
"name": "powr",
|
||||
"slug": "powr",
|
||||
"version": "1.0.0",
|
||||
"orientation": "portrait",
|
||||
"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
|
||||
[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
|
||||
|
||||
### Functional Requirements
|
||||
- [List of must-have functionality]
|
||||
- [User-facing features]
|
||||
- [Core capabilities]
|
||||
- Store and process exercise definitions with complete metadata
|
||||
- Support workout template creation and management
|
||||
- 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
|
||||
- Performance targets
|
||||
- Security requirements
|
||||
- Reliability goals
|
||||
- Usability standards
|
||||
- Query response time < 100ms for common operations
|
||||
- Support concurrent read/write operations safely
|
||||
- Minimize memory usage through efficient caching
|
||||
- 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
|
||||
|
||||
### 1. [Major Decision Area]
|
||||
[Description of approach chosen]
|
||||
### 1. Storage Architecture
|
||||
Use a dual storage approach with separate tables for raw events and processed data:
|
||||
|
||||
Rationale:
|
||||
- [Key reason]
|
||||
- [Supporting factors]
|
||||
- [Trade-offs considered]
|
||||
- Maintains perfect relay replication capability
|
||||
- Enables efficient local querying
|
||||
- Supports dependency tracking
|
||||
- Facilitates future sync operations
|
||||
- Allows for flexible schema evolution
|
||||
|
||||
### 2. [Major Decision Area]
|
||||
[Description of approach chosen]
|
||||
### 2. Cache Management
|
||||
Implement an LRU cache system with configurable limits:
|
||||
|
||||
Rationale:
|
||||
- [Key reason]
|
||||
- [Supporting factors]
|
||||
- [Trade-offs considered]
|
||||
- Improves read performance for common queries
|
||||
- Manages memory usage effectively
|
||||
- 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
|
||||
|
||||
### 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
|
||||
|
||||
```typescript
|
||||
// Key interfaces/types
|
||||
interface ComponentName {
|
||||
// Critical fields
|
||||
interface DbService {
|
||||
// Core database operations
|
||||
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
|
||||
function mainOperation() {
|
||||
// Key logic
|
||||
interface CacheManager {
|
||||
// Cache configuration
|
||||
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
|
||||
|
||||
### Phase 1: [Initial Phase]
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
### Phase 1: Core Infrastructure (Week 1-2)
|
||||
1. Set up base schema and migrations
|
||||
2. Implement DbService class
|
||||
3. Add basic CRUD operations
|
||||
4. Create test infrastructure
|
||||
|
||||
### Phase 2: [Next Phase]
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
### Phase 2: Cache Layer (Week 2-3)
|
||||
1. Implement CacheManager
|
||||
2. Add LRU caching
|
||||
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
|
||||
|
||||
### Unit Tests
|
||||
- [Key test areas]
|
||||
- [Critical test cases]
|
||||
- [Test tooling]
|
||||
- Schema creation and migrations
|
||||
- CRUD operations for all entities
|
||||
- Cache operations and invalidation
|
||||
- Query builder functions
|
||||
|
||||
### Integration Tests
|
||||
- [End-to-end scenarios]
|
||||
- [Cross-component tests]
|
||||
- [Test environments]
|
||||
- End-to-end workflow testing
|
||||
- Template dependency handling
|
||||
- Sync operations
|
||||
- Performance benchmarks
|
||||
|
||||
### Performance Tests
|
||||
- Query response times
|
||||
- Cache hit rates
|
||||
- Write operation latency
|
||||
- Memory usage patterns
|
||||
|
||||
## Observability
|
||||
|
||||
### Logging
|
||||
- [Key log points]
|
||||
- [Log levels]
|
||||
- [Critical events]
|
||||
- Schema migrations
|
||||
- Cache operations
|
||||
- Query performance
|
||||
- Error conditions
|
||||
|
||||
### Metrics
|
||||
- [Performance metrics]
|
||||
- [Business metrics]
|
||||
- [System health metrics]
|
||||
- Query response times
|
||||
- Cache hit/miss rates
|
||||
- Database size
|
||||
- Operation counts
|
||||
|
||||
## Future Considerations
|
||||
|
||||
### Potential Enhancements
|
||||
- [Future feature ideas]
|
||||
- [Scalability improvements]
|
||||
- [Technical debt items]
|
||||
- Advanced caching strategies
|
||||
- Full-text search
|
||||
- Data compression
|
||||
- Cloud backup options
|
||||
|
||||
### Known Limitations
|
||||
- [Current constraints]
|
||||
- [Technical restrictions]
|
||||
- [Scope boundaries]
|
||||
- SQLite concurrent access
|
||||
- Initial sync performance
|
||||
- Cache memory constraints
|
||||
- Platform-specific issues
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Runtime Dependencies
|
||||
- [External services]
|
||||
- [Libraries]
|
||||
- [System requirements]
|
||||
- expo-sqlite
|
||||
- @react-native-async-storage/async-storage
|
||||
- NDK (future)
|
||||
|
||||
### Development Dependencies
|
||||
- [Build tools]
|
||||
- [Test frameworks]
|
||||
- [Development utilities]
|
||||
- Jest
|
||||
- TypeScript
|
||||
- SQLite development tools
|
||||
|
||||
## Security Considerations
|
||||
- [Security measures]
|
||||
- [Privacy concerns]
|
||||
- [Data protection]
|
||||
|
||||
## Rollout Strategy
|
||||
|
||||
### Development Phase
|
||||
1. [Development steps]
|
||||
2. [Testing approach]
|
||||
3. [Documentation needs]
|
||||
|
||||
### Production Deployment
|
||||
1. [Deployment steps]
|
||||
2. [Migration plan]
|
||||
3. [Monitoring setup]
|
||||
- Input validation
|
||||
- Query parameterization
|
||||
- Event signature verification
|
||||
- Access control
|
||||
|
||||
## References
|
||||
- [Related documents]
|
||||
- [External resources]
|
||||
- [Research materials]
|
||||
- NDK SQLite Implementation
|
||||
- Nostr NIP-01 Specification
|
||||
- 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",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "rnr-test",
|
||||
"name": "powr",
|
||||
"version": "1.0.0",
|
||||
"hasInstallScript": true,
|
||||
"dependencies": {
|
||||
|
@ -1,5 +1,5 @@
|
||||
{
|
||||
"name": "rnr-test",
|
||||
"name": "powr",
|
||||
"main": "index.js",
|
||||
"version": "1.0.0",
|
||||
"scripts": {
|
||||
|
Loading…
x
Reference in New Issue
Block a user