dturkuler/harmonyadvisor repository overview

⁠Harmony Advisor

Harmony Advisor is a sophisticated React application design to interpret complex Human Design mechanics into practical, real-time guidance for relationships and personal wellness. By combining precise bodygraph calculations with advanced AI (Google Gemini or Ollama), it offers neutral, jargon-free advice tailored to your specific energetic dynamics.

⁠🌟 Key Features

• 🎭 Multi-Role Dynamics: Tailored guidance for various relationships including Spouses, Children, Parents, Bosses, Colleagues, and Friends, as well as Self-reflection.

• ⚡ Energetic Empathy: "Sage Analysis" explains the "Why" behind dynamics before offering advice.

• 🎯 Targeted Context Categories: Focused advice for specific scenarios:

  • Conflict Resolution
  • Setting Boundaries
  • Making Requests
  • Habits & Routines
  • Emotional Support
  • Wellness & Diet (PHS)

• 💎 Premium Glassmorphism UI: A stunning, modern interface featuring "Ethereal Bioluminescence" aesthetics, smooth animations (powered by framer-motion), and adaptive dark mode.

• ☁️ Secure Cloud Sync: Integrated Appwrite backend for secure, cross-device profile synchronization and authentication.

• 🛡️ Admin Command Center: A powerful, dashboard for user management, system orchestration, and "God Mode" profile data inspection.

• 🏆 Pro Subscription: Stripe-integrated subscription system with "Pro" badging and premium feature access.

• 🤖 AI-Powered Analysis: Leverages Large Language Models (LLM) to generate:

  • "Try Saying This" Scripts
  • Actionable "Do This Today" tasks
  • 7-Day Resolution Plans
  • Deep Mechanical Analysis (Why is this happening?)

• 🔮 Real-Time Human Design: Calculates Charts (Type, Strategy, Authority, Profile) on-the-fly using a dedicated calculation API.

• 🌍 Full Localization: Seamlessly switch between English and Turkish interfaces and advice.

• ⚡ Quick-Fill Context: Pre-populated, role-specific examples to quickly describe common situations (e.g., "Dirty dishes", "Homework struggles").

• 🎨 Premium UI: A polished, mobile-first interface built with Tailwind CSS.

• 🚫 Lightweight Performance: Removed legacy Three.js and complex background animations to improve page load times and device compatibility.

⁠🛠️ Tech Stack

• Framework: React 19⁠ + Vite 7⁠
• Styling: Tailwind CSS 3.4⁠
• AI Integration:
  • Google Gemini⁠ (via @google/generative-ai)
  • Ollama⁠ (Local LLM support)
• Backend & Auth: Appwrite⁠ (Cloud or Self-Hosted)
• Payments: Stripe⁠
• API Client: Custom Fetch/Axios wrappers
• State Management: React Hooks, Context & Appwrite Realtime

⁠🚀 Getting Started

⁠Prerequisites

• Node.js (v18+ recommended)
• npm or yarn

⁠Installation

1. Clone the repository:

   git clone https://github.com/yourusername/harmonyadvisor.git
   cd harmonyadvisor
   

   Copy

2. Install dependencies:

   npm install
   

   Copy

3. Configure Environment: Create a .env file in the root directory using the template below:

   # Required: API Key for the Human Design Calculation Service
   VITE_HD_API_KEY=your_hd_api_key_here
   
   # Google Gemini Configuration (Default Provider)
   VITE_GEMINI_API_KEY=your_gemini_key_here
   VITE_GEMINI_MODEL=gemini-2.0-flash-exp
   
   # Optional: Ollama Configuration (Local AI)
   # VITE_AI_PROVIDER=ollama
   # VITE_OLLAMA_BASE_URL=http://localhost:11434
   

   Copy

4. Run the Development Server:

   npm run dev
   

   Copy

   The app will start at http://localhost:32100 (configured in vite.config.js).

⁠📖 Usage Guide

1. Select Module: Choose your journey from the Home Screen:
   • Guided Conflict Resolution: For relationship dynamics (Spouse, Child, Boss).
   • Personal Mechanic Reports: For deep-dive self-discovery and reports.
2. Select Focus: Pick a category (e.g., "Conflict", "Wellness", "Communication").
3. Enter Data:
   • Profiles: Select your Energetic Profile for yourself and your partner from your saved profiles.
   • Context: Describe the situation using the text box or select a "Quick Fill" example.
4. Generate: Click "Generate Guidance" to receive your personalized analysis.
5. Review: Read the tailored scripts, immediate actions, and long-term plans.

⁠📂 Project Structure

harmonyadvisor/
├── .docs/                  # Documentation & Knowledge Base
├── public/                 # Static assets
├── src/
│   ├── components/         # Reusable UI Components
│   │   ├── admin/          # Admin Dashboard & Tools
│   │   ├── selectors/      # Module, Role & Category Selectors
│   │   ├── ProfileInput.jsx# Birth Data Form
│   │   └── GuidanceResult.jsx # Result Display
│   ├── services/           # Business Logic
│   │   ├── api.js          # HD API & Gemini Interface
│   │   ├── auth.js         # Appwrite Authentication
│   │   ├── storage.js      # Appwrite Database Operations
│   │   ├── ollama.js       # Ollama Client
│   │   └── prompts.js      # AI Prompt Templates
│   ├── data/               # Static Data (Examples)
│   ├── translations.js     # i18n Dictionary (EN/TR)
│   ├── App.jsx             # Main Application Logic
│   └── main.jsx            # Entry Point
├── scripts/                # Automation scripts (Docker push, etc)
├── .env                    # Env variables (not committed)
├── Dockerfile              # Multi-stage production build
├── docker-compose.yml      # Container orchestration
├── docker-entrypoint.sh    # Runtime environment injection script
├── nginx.conf              # Production web server config
├── tailwind.config.js      # CSS Configuration
└── vite.config.js          # Build & Proxy Configuration

⁠⚙️ Configuration Details

⁠Proxy Setup

To avoid CORS issues during local development, vite.config.js is configured to proxy requests:

• /api/hd -> Proxies to the remote Human Design API.
• /api/ollama -> Proxies to your local Ollama instance (strips Origin header to bypass 403 errors).

⁠AI Providers

The app works primarily with Google Gemini. To switch to Ollama:

1. Ensure Ollama is running (ollama serve).
2. Set VITE_AI_PROVIDER=ollama in your .env file.
3. Ensure you have a model pulled (e.g., mistral or llama3) and referenced in the code defaults.

⁠🐳 Docker & Deployment

The application is containerized and optimized for performance and flexibility.

⁠Local Docker Build

docker build -t harmonyadvisor .
docker run -p 9301:80 harmonyadvisor

⁠Production Deployment (Advanced)

Harmony Advisor uses a runtime environment injection system. This allows you to update API keys and configurations on your server without rebuilding the Docker image.

1. Pull the latest image:

   docker pull dturkuler/harmonyadvisor:latest
   

   Copy

2. Configure docker-compose.yml:

   services:
     app:
       image: dturkuler/harmonyadvisor:latest
       ports:
         - "9301:80"
       environment:
         - VITE_HD_API_KEY=your_key
         - VITE_GEMINI_API_KEY=your_key
         - VITE_AI_PROVIDER=gemini # or ollama
   

   Copy

3. Deploy:

   docker-compose up -d
   

   Copy

⁠Deployment Automation

For maintainers, use the automated build script:

./scripts/deploy_to_hub.sh

⁠This script handles versioning, multi-stage building, and pushing both versioned and latest tags to Docker Hub.

⁠🤝 Contributing

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

⁠📄 License

Distributed under the MIT License. See LICENSE for more information.