🗄️ Database Structure

Hey, Inner Journey architects! This document outlines the blueprint for how Inner Journey stores and manages data within Firestore. Our goal is a secure, scalable, and efficient structure to power a platform dedicated to personal growth and self-development. This foundation supports everything from user profiles and personalized insights to coach-led programs and financial tracking. Be proud – you’re crafting the core of something truly transformative! 🌟

🎯 Purpose & Overview

Our Firestore database is meticulously designed to enable Inner Journey’s core functionalities:

• 👤 Personal Profiling: Securely stores user data including birth details for astrology/numerology calculations and preferences for tailored personal growth insights.
• ✍️ Dynamic Journal: Captures user reflections (text, audio, video) as an integral part of their self-development journey.
• 💪 Activations and Programs: Manages coach-created activities ("activations") and structured personal growth programs.
• 🤝 Coach Interactions: Facilitates interactions between coaches and users, including assigning activations and monitoring progress on their journey.
• 💸 Payments and Payouts: Reliably tracks customer payments for premium features/programs and ensures accurate coach payouts for financial transparency and financial management.

📝 Note: We leverage Firestore for its scalability and real-time capabilities. An in-memory fallback (call_status) might be used temporarily during development phases but the goal is full Firestore implementation.

🗂️ Collections Overview

Here’s a visual representation of how our data is organized in Firestore:

👤 Collection: users

Description: Stores individual user profiles, preferences, and calculated data for personalization and AI-driven insights. Document ID: User’s unique Firebase Authentication UID (e.g., "firebase-uid-123").

Fields:

• userId: String – Unique user identifier (matches Auth UID).
• birthDate: String – User's birth date in ISO 8601 format (e.g., "1990-05-15"). Necessary for astrological calculations.
• birthTime: String – User's birth time (e.g., "14:30"). Optional but enhances astrological precision.
• birthLocation: String – User's birth location (e.g., "Stockholm, Sweden"). Used for astrological chart generation.
• phoneNumber: String – Verified phone number (e.g., "+46701234567"). Used for authentication or communication.
• createdAt: Timestamp – Timestamp indicating when the user profile was created.
• uiStyle: String – User's preferred UI theme (e.g., "clean", "professional", "calm").
• focusArea: String – Primary goal selected during onboarding (e.g., "stress_relief", "career_growth"). Guides initial personal development path.
• timeCommitment: Number – Preferred daily time commitment in minutes (e.g., 15). Helps tailor program suggestions.
• personalityType: Object – Stores personality assessment results:
  • traits: Array – Key personality traits (e.g., ["introvert", "intuitive", "thinker"]).
  • astroSign: String – Calculated sun sign (e.g., "Taurus").
  • lifePathNumber: Number – Calculated numerology life path number (e.g., 7).
• neuroTendencies: Object – Self-reported or assessed neurodiversity indicators (used sensitively):
  • adhdScore: Number – Indicator score (0-10 scale, e.g., 3).
  • autismScore: Number – Indicator score (0-10 scale, e.g., 2).
• wellbeingFlags: Object – Automatically flagged potential wellbeing concerns based on user input (requires careful handling):
  • depressionRisk: Boolean – Flag based on screening question answers.
  • suicideRisk: Boolean – Flag based on screening question answers (requires immediate protocol if true).
• answers: Array – Raw answers from onboarding questionnaires (e.g., [{"questionId": "q1", "answer": "Draining"}]).

💡 Flexibility: Consider adding fields like moonSign, risingSign, progressLevel, preferredPronouns.

💪 Collection: activations

Description: Contains predefined or coach-created activities designed for user engagement and growth (e.g., meditations, journaling prompts, physical exercises). Document ID: Unique activation identifier (e.g., "hemisync_meditation_001").

Fields:

• activationId: String – Unique ID for this activation (matches Document ID).
• title: String – Clear and engaging title (e.g., "10-Minute Morning Awareness Meditation").
• type: String – The format of the activation (e.g., "audio", "video", "text_prompt", "live_interaction", "physical_exercise").
• description: String – A brief explanation of the activation and its purpose (e.g., "A guided audio meditation using binaural beats to enhance focus.").
• duration: Number – Estimated duration in minutes (e.g., 10).
• mediaUrl: String – Link to media file in Firebase Storage (if applicable, e.g., for audio/video types). Can be null.
• category: String – Helps categorize activations (e.g., "mindfulness", "stress_reduction", "creativity", "emotional_intelligence").
• createdBy: String – UID of the coach or admin who created the activation (e.g., "coach_uid_123"). Links to the users collection.

💡 Flexibility: Add fields like difficultyLevel (beginner, intermediate, advanced), requiredEquipment (Array<String>), tags (Array<String>).

📝 Collection: user_activations

Description: Tracks a user's engagement and progress with specific activations. This forms the core of the Dynamic Journal and personalized journey tracking. Document ID: Composite ID, typically userId_activationId_timestamp or a unique UUID (e.g., "firebase-uid-123_hemisync-001_1678886400" or generated UUID).

Fields:

• userActivationId: String – Unique ID for this specific instance of a user doing an activation.
• userId: String – Links to the users collection.
• activationId: String – Links to the activations collection.
• programId: String (Nullable) – Links to the programs collection if this activation was completed as part of a specific program.
• assignedBy: String (Nullable) – Coach UID if assigned directly.
• startedAt: Timestamp – When the user started the activation.
• completedAt: Timestamp (Nullable) – When the user marked the activation as complete.
• status: String – Current status (e.g., "assigned", "in_progress", "completed", "skipped").
• log: Object – User's reflection data (Dynamic Journal entry):
  • text: String – Written reflection or notes (e.g., "Felt surprisingly calm and focused afterward.").
  • audioUrl: String (Nullable) – Link to a recorded audio reflection in Firebase Storage.
  • videoUrl: String (Nullable) – Link to a recorded video reflection in Firebase Storage.
  • moodBefore: String (Nullable) – User-reported mood before starting (e.g., "stressed").
  • moodAfter: String (Nullable) – User-reported mood after completing (e.g., "calm").
  • rating: Number (Nullable) – User rating of the activation (e.g., 1-5 stars).
  • aiAnalysis: Object (Nullable) – Results from AI analysis of the reflection (e.g., { "sentimentScore": 0.8, "keyThemes": ["calm", "focus"] }).
• sessionId: String (Nullable) – Links to live_sessions if completed during a live session.

💡 Flexibility: Add feedbackForCoach, privateNote.

👥 Collection: live_sessions

Description: Manages real-time, scheduled group or one-on-one interactions, often involving specific activations or programs. Document ID: Unique session identifier (e.g., "live_session_xyz789").

Fields:

• liveSessionId: String – Unique ID for this live session.
• title: String – Name of the live session (e.g., "Weekly Group Check-in").
• activationId: String (Nullable) – Links to an activations if the session revolves around one (e.g., a live guided meditation).
• programId: String (Nullable) – Links to programs if the session is part of a program schedule.
• coachId: String – UID of the hosting coach. Links to users.
• participants: Array – List of userIds participating in the session.
• startTime: Timestamp – Scheduled start time and date.
• endTime: Timestamp – Scheduled end time and date.
• status: String – Current status (e.g., "scheduled", "live", "completed", "cancelled").
• meetingUrl: String (Nullable) – Link to the video conferencing platform.
• reflections: Array – Post-session reflections (can reference user_activations or store simple text):
  • userId: String – User submitting the reflection.
  • text: String – Brief reflection text (e.g., "Great energy in the group today.").
  • submittedAt: Timestamp.

💡 Flexibility: Add sessionRecordingUrl, maxParticipants.

✅ Collection: consents

Description: Records user consent for GDPR compliance, terms of service, and privacy policies, ensuring traceability. Document ID: User’s UID (userId).

Fields:

• userId: String – Links back to the users collection (matches Document ID).
• consentsGiven: Array – List of specific consents granted:
  • type: String – Type of consent (e.g., "terms_of_service", "privacy_policy", "data_processing", "marketing_emails").
  • version: String – Version of the document consented to (e.g., "v1.1").
  • agreedAt: Timestamp – Timestamp when this specific consent was given.
  • status: String – "granted" or "revoked".

💡 Flexibility: Store IP address or user agent at time of consent for extra verification if required by regulations.

📞 Collection: sessions (Temporary/Legacy)

Description: Intended to manage temporary session data, potentially replacing an older in-memory call_status system during transitions or for specific short-lived state needs (e.g., phone verification codes). Note: Evaluate if this is still necessary or if state can be managed differently (e.g., within users document or client-side). Document ID: Unique sessionId (e.g., "temp_session_abc123").

Fields:

• sessionId: String – Unique session ID.
• userId: String – Links to users.
• type: String – Type of session (e.g., "phone_verification", "password_reset").
• data: Object – Session-specific data (e.g., {"verificationCode": "123456", "expiresAt": Timestamp}).
• createdAt: Timestamp – When the session was created.

💡 Best Practice: Minimize reliance on separate temporary session collections in Firestore; leverage client-state or user document sub-collections where possible.

📚 Collection: programs

Description: Defines structured, multi-step personal growth programs created by coaches, composed of ordered activations. Document ID: Unique program identifier (e.g., "program_dream_to_reality_001").

Fields:

• programId: String – Unique ID for the program.
• title: String – Compelling program title (e.g., "Unlock Your Potential: A 4-Week Journey").
• description: String – Detailed overview of the program, its goals, and target audience.
• durationWeeks: Number – Expected program length in weeks (e.g., 4).
• createdBy: Array – List of coach userIds who created/own the program.
• modules: Array – Structured modules containing activations:
  • moduleId: String – Unique ID for the module (e.g., "week1").
  • title: String – Module title (e.g., "Week 1: Foundation & Awareness").
  • activations: Array – Ordered list of activations within the module:
    • activationId: String – Links to activations.
    • day: Number – Recommended day within the module/week to perform (e.g., 1).
    • isOptional: Boolean – Whether the activation is mandatory.
• difficulty: String – Program difficulty level (e.g., "beginner", "intermediate", "advanced").
• category: String – Primary category (e.g., "career_development", "wellbeing", "relationships").
• tags: Array<String> – Keywords for searchability (e.g., ["mindfulness", "goal-setting", "resilience"]).
• price: Number (Nullable) – Price if it's a premium program (e.g., 499).
• currency: String (Nullable) – Currency for the price (e.g., "SEK").

💡 Flexibility: Add prerequisites (e.g., required prior program), enrollmentCount, averageRating.

💳 Collection: payments

Description: Logs customer transactions related to subscriptions, program purchases, or other premium features, crucial for financial tracking. Document ID: Unique payment identifier (often generated by the payment processor or system, e.g., "pay_123abc").

Fields:

• paymentId: String – Unique ID for this payment record.
• userId: String – Links to the users collection (the customer).
• amount: Number – Payment amount in the smallest currency unit (e.g., 49900 for 499.00 SEK).
• currency: String – Currency code (e.g., "SEK", "USD").
• paymentDate: Timestamp – Timestamp when the payment was processed.
• status: String – Payment status (e.g., "succeeded", "pending", "failed", "refunded").
• processor: String – Payment processor used (e.g., "stripe", "paypal").
• processorPaymentId: String – The transaction ID from the payment processor (e.g., Stripe's pi_... or cs_...).
• description: String – Description of what was purchased (e.g., "Subscription renewal", "Enrollment in Program X").
• programId: String (Nullable) – Links to programs if the payment was for a specific program.
• subscriptionId: String (Nullable) – Links to a subscription record if part of a recurring payment.

💡 Flexibility: Add invoiceUrl, refundDetails (object).

💸 Collection: payouts

Description: Tracks payouts made to coaches for their contributions (e.g., program sales commissions, live session fees). Essential for coach financial management. Document ID: Unique payout identifier (e.g., "payout_xyz789").

Fields:

• payoutId: String – Unique ID for this payout record.
• coachId: String – Links to the users collection (the coach receiving the payout).
• amount: Number – Payout amount in the smallest currency unit (e.g., 40000 for 400.00 SEK).
• currency: String – Currency code (e.g., "SEK", "USD").
• payoutDate: Timestamp – Timestamp when the payout was initiated or completed.
• status: String – Payout status (e.g., "pending", "processing", "completed", "failed").
• processor: String – Payout processor used (e.g., "stripe_connect", "paypal", "bank_transfer").
• processorPayoutId: String (Nullable) – The transaction ID from the payout processor.
• fortnoxReference: String (Nullable) – Reference ID for accounting systems like Fortnox after synchronization.
• relatedPaymentIds: Array<String> (Nullable) – Links to payments that contributed to this payout amount.

💡 Flexibility: Add payoutMethodDetails (e.g., last 4 digits of bank account), calculationPeriod (start/end dates).

✏️ Data Usage Examples

• 🌱 Onboarding: Data from users (birth info, goals) drives initial personalization. consents ensures compliance from the start.
• 💪 Personal Journeys: programs define structured paths. user_activations logs every step, reflection, and insight, forming the core personal growth record.
• ✍️ Dynamic Journal: The log object within user_activations is the Dynamic Journal, capturing text, audio, video, and potentially AI-analyzed insights.
• 🤝 Coach Interactions: Coaches create activations and programs. They monitor progress via user_activations and interact in live_sessions.
• 💸 Financial Management: payments tracks incoming revenue from users. payouts ensures coaches are compensated correctly based on their contributions.

🛡️ Security & GDPR Compliance

• 🔒 Encryption: Firestore encrypts data at rest by default. All data transmission uses HTTPS.
• 🔑 Access Control: Firestore Security Rules are critical. They must enforce that:
  • Users can only read/write their own data (users, user_activations, consents).
  • Coaches can read data of users they are assigned to or participants in their programs/sessions, but cannot modify sensitive user base data.
  • Coaches can manage the activations and programs they create.
  • Admin roles have broader access for maintenance and support.
• 📜 GDPR:
  • Consent is explicitly tracked in the consents collection.
  • Data Subject Access Requests (DSARs) can be fulfilled by querying data linked by userId.
  • Data deletion requests require removing the users document and associated documents in other collections (e.g., user_activations, consents, potentially anonymizing live_session participation). Define clear data retention policies (e.g., logs deleted after 90 days unless actively part of user record).

Refer to a dedicated Security Principles document for detailed Firestore rules examples.

Let’s continue building a robust and secure database that truly empowers the Inner Journey experience – your meticulous work here is fundamental! 🚀