{"id":29128085,"url":"https://github.com/chanmeng666/femtracker-agent","last_synced_at":"2026-04-09T18:43:24.527Z","repository":{"id":301704476,"uuid":"1001446470","full_name":"ChanMeng666/femtracker-agent","owner":"ChanMeng666","description":"【⭐️ Star this repo to support women's health innovation! 】🌸 AI-powered women's health companion built with Next.js 15, React 19, Python LangGraph \u0026 Supabase. Features 8 specialized AI agents, real-time health insights, cycle prediction, fertility tracking \u0026 comprehensive wellness monitoring with 90% faster performance through Redis caching.","archived":false,"fork":false,"pushed_at":"2025-06-28T09:38:15.000Z","size":3626,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-28T10:29:05.896Z","etag":null,"topics":["ai-agents","copilotkit","cycle-tracking","fertility-tracking","health-tracking","healthcare","langgraph","nextjs","openai","python","react","redis","supabase","typescript","women-health"],"latest_commit_sha":null,"homepage":"https://femtracker-agent.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChanMeng666.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-13T11:51:35.000Z","updated_at":"2025-06-28T09:38:18.000Z","dependencies_parsed_at":"2025-06-28T10:39:36.039Z","dependency_job_id":null,"html_url":"https://github.com/ChanMeng666/femtracker-agent","commit_stats":null,"previous_names":["chanmeng666/femtracker-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ChanMeng666/femtracker-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Ffemtracker-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Ffemtracker-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Ffemtracker-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Ffemtracker-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChanMeng666","download_url":"https://codeload.github.com/ChanMeng666/femtracker-agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Ffemtracker-agent/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262690484,"owners_count":23349168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","copilotkit","cycle-tracking","fertility-tracking","health-tracking","healthcare","langgraph","nextjs","openai","python","react","redis","supabase","typescript","women-health"],"created_at":"2025-06-30T01:02:34.004Z","updated_at":"2026-04-09T18:43:24.515Z","avatar_url":"https://github.com/ChanMeng666.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\u003ca name=\"readme-top\"\u003e\u003c/a\u003e\n\n[![Project Banner](./public/chan-meng-banner.svg)](#)\n\n# 🌸 FemTracker Agent\u003cbr/\u003e\u003ch3\u003eAI-Powered Women's Health Companion\u003c/h3\u003e\n\nAn innovative women's health tracking platform that leverages cutting-edge AI multi-agent technology to provide personalized health insights, cycle predictions, and comprehensive wellness monitoring.\u003cbr/\u003e\nSupports intelligent health analytics, real-time AI assistance, and extensible agent architecture with advanced machine learning capabilities.\u003cbr/\u003e\nOne-click **FREE** deployment of your personal health companion.\n\n[Live Demo][project-link] · [Documentation][docs] · [Agent System][agent-docs] · [Issues][github-issues-link]\n\n\u003cbr/\u003e\n\n[![🚀 Visit Live Site 🚀](https://gradient-svg-generator.vercel.app/api/svg?text=%F0%9F%9A%80Visit%20Live%20Site%F0%9F%9A%80\u0026color=000000\u0026height=60\u0026gradientType=radial\u0026duration=6s\u0026color0=ffffff\u0026template=pride-rainbow)][project-link]\n\n\u003cbr/\u003e\n\n\u003c!-- SHIELD GROUP --\u003e\n\n[![][github-release-shield]][github-release-link]\n[![][vercel-shield]][vercel-link]\n[![][discord-shield]][discord-link]\u003cbr/\u003e\n[![][github-action-test-shield]][github-action-test-link]\n[![][github-releasedate-shield]][github-releasedate-link]\u003cbr/\u003e\n[![][github-contributors-shield]][github-contributors-link]\n[![][github-forks-shield]][github-forks-link]\n[![][github-stars-shield]][github-stars-link]\n[![][github-issues-shield]][github-issues-link]\n[![][github-license-shield]][github-license-link]\u003cbr\u003e\n\n**Share FemTracker Agent**\n\n[![][share-x-shield]][share-x-link]\n[![][share-telegram-shield]][share-telegram-link]\n[![][share-whatsapp-shield]][share-whatsapp-link]\n[![][share-reddit-shield]][share-reddit-link]\n[![][share-linkedin-shield]][share-linkedin-link]\n\n\u003csup\u003e🌟 Pioneering the future of women's health technology. Built for the next generation of personalized healthcare.\u003c/sup\u003e\n\n**Tech Stack Badges:**\n\n\u003cdiv align=\"center\"\u003e\n\n \u003cimg src=\"https://img.shields.io/badge/next.js-%23000000.svg?style=for-the-badge\u0026logo=nextdotjs\u0026logoColor=white\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/react-%2320232a.svg?style=for-the-badge\u0026logo=react\u0026logoColor=%2361DAFB\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge\u0026logo=typescript\u0026logoColor=white\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/python-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/supabase-%2334D058.svg?style=for-the-badge\u0026logo=supabase\u0026logoColor=white\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/tailwindcss-%2338B2AC.svg?style=for-the-badge\u0026logo=tailwindcss\u0026logoColor=white\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/langgraph-%23FF6B6B.svg?style=for-the-badge\u0026logo=langchain\u0026logoColor=white\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/redis-%23DD0031.svg?style=for-the-badge\u0026logo=redis\u0026logoColor=white\"/\u003e\n\n\u003c/div\u003e\n\n\u003c/div\u003e\n\n\u003e [!IMPORTANT]\n\u003e This project demonstrates cutting-edge AI agent orchestration technology combined with comprehensive women's health tracking. It features 8 specialized AI agents, real-time health analytics, and WHO-standard health scoring algorithms. The system provides personalized health insights through intelligent agent coordination.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ckbd\u003e📑 Table of Contents\u003c/kbd\u003e\u003c/summary\u003e\n\n#### TOC\n\n- [🌸 FemTracker Agent](#-femtracker-agent)\n      - [TOC](#toc)\n  - [🌟 Introduction](#-introduction)\n  - [✨ Key Features](#-key-features)\n    - [`1` Advanced AI Multi-Agent System](#1-advanced-ai-multi-agent-system)\n    - [`2` Comprehensive Health Analytics](#2-comprehensive-health-analytics)\n    - [`*` Additional Features](#-additional-features)\n  - [🛠️ Tech Stack](#️-tech-stack)\n  - [🏗️ Architecture](#️-architecture)\n    - [Multi-Agent System Architecture](#multi-agent-system-architecture)\n    - [Data Flow](#data-flow)\n    - [Component Structure](#component-structure)\n  - [⚡️ Performance](#️-performance)\n  - [🚀 Getting Started](#-getting-started)\n    - [Prerequisites](#prerequisites)\n    - [Quick Installation](#quick-installation)\n    - [Environment Setup](#environment-setup)\n    - [Development Mode](#development-mode)\n  - [🛳 Deployment](#-deployment)\n    - [`A` Cloud Deployment](#a-cloud-deployment)\n    - [`B` Docker Deployment](#b-docker-deployment)\n    - [`C` Environment Variables](#c-environment-variables)\n  - [📖 Usage Guide](#-usage-guide)\n    - [Basic Usage](#basic-usage)\n    - [AI Agent System](#ai-agent-system)\n    - [Health Scoring System](#health-scoring-system)\n  - [🤖 AI Agents](#-ai-agents)\n  - [📦 Database Schema](#-database-schema)\n  - [⌨️ Development](#️-development)\n    - [Local Development](#local-development)\n    - [Adding New Agents](#adding-new-agents)\n    - [Creating Custom Health Modules](#creating-custom-health-modules)\n  - [🤝 Contributing](#-contributing)\n  - [📄 License](#-license)\n  - [👥 Team](#-team)\n\n####\n\n\u003cbr/\u003e\n\n\u003c/details\u003e\n\n## 🌟 Introduction\n\nWe are passionate developers creating next-generation women's health solutions. By adopting cutting-edge AI agent technology and modern development practices, we aim to provide users with powerful, intelligent, and personalized health tracking tools.\n\nWhether you're tracking your menstrual cycle, fertility journey, or overall wellness, FemTracker Agent serves as your intelligent health companion. This project showcases advanced AI orchestration, real-time health analytics, and comprehensive women's health monitoring.\n\n\u003e [!NOTE]\n\u003e - Node.js \u003e= 18.0 required\n\u003e - Python \u003e= 3.12 required for AI agents\n\u003e - Supabase account required for database\n\u003e - OpenAI API key required for AI features\n\u003e - Redis optional for enhanced performance\n\n| [![][demo-shield-badge]][demo-link]   | No installation required! Experience our AI-powered health tracking platform.                           |\n| :------------------------------------ | :--------------------------------------------------------------------------------------------- |\n| [![][discord-shield-badge]][discord-link] | Join our community! Connect with developers and health-conscious users. |\n\n\u003e [!TIP]\n\u003e **⭐ Star us** to receive all release notifications and support the development of open-source women's health technology!\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003ckbd\u003e⭐ Star History\u003c/kbd\u003e\u003c/summary\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=ChanMeng666%2Ffemtracker-agent\u0026theme=dark\u0026type=Date\"\u003e\n    \u003cimg width=\"100%\" src=\"https://api.star-history.com/svg?repos=ChanMeng666%2Ffemtracker-agent\u0026type=Date\"\u003e\n  \u003c/picture\u003e\n\u003c/details\u003e\n\n## 🎥 Project Demo Video\n\n\u003e [!TIP]\n\u003e **Watch the complete project walkthrough!** Get a comprehensive overview of FemTracker Agent's AI-powered features and capabilities.\n\n\u003cdiv align=\"center\"\u003e\n\n[![FemTracker Agent - AI-Powered Women's Health Companion Demo](https://img.youtube.com/vi/VVCQKmeEtRs/maxresdefault.jpg)](https://youtu.be/VVCQKmeEtRs?si=j74lzM_UfeACgYKu)\n\n**🎬 [Watch Project Demo on YouTube](https://youtu.be/VVCQKmeEtRs?si=j74lzM_UfeACgYKu)**\n\n*Complete project walkthrough showcasing AI agent system, health tracking features, and real-time analytics*\n\n\u003c/div\u003e\n\n**What you'll see in the demo:**\n- 🤖 **AI Agent System**: Live demonstration of 8 specialized health agents\n- 📊 **Health Analytics**: WHO-standard health scoring and insights generation  \n- 🌸 **Health Modules**: Cycle tracking, fertility monitoring, nutrition guidance\n- 💬 **Conversational AI**: Natural language health assistance in action\n- 📱 **User Experience**: Complete user journey from signup to advanced features\n- 🔧 **Technical Architecture**: Behind-the-scenes look at LangGraph coordination\n\n## ✨ Key Features\n\n### `1` [Advanced AI Multi-Agent System][docs-ai-agents]\n\nExperience next-generation health tracking through our revolutionary 8-agent AI system. Each specialized agent provides domain-specific expertise while our main coordinator ensures seamless interaction and intelligent routing.\n\n**Agent Specializations:**\n- 🤖 **Main Coordinator**: Intelligent request routing and agent orchestration\n- 📅 **Cycle Tracker**: Menstrual cycle prediction and pattern analysis\n- 🌸 **Fertility Tracker**: Ovulation prediction and conception guidance  \n- 💚 **Symptom Mood**: Emotional health and symptom pattern recognition\n- 🥗 **Nutrition Guide**: Personalized dietary recommendations and meal planning\n- 💪 **Exercise Coach**: Cycle-aware fitness guidance and activity tracking\n- ✨ **Lifestyle Manager**: Sleep optimization and stress management\n- 🧠 **Health Insights**: Comprehensive analytics and correlation analysis\n\nKey capabilities include:\n- 🚀 **Real-time Agent Coordination**: Intelligent routing and response orchestration\n- 🔧 **LangGraph Integration**: Advanced workflow management and state handling\n- 📱 **CopilotKit Integration**: Seamless conversational AI experience\n- 🛡️ **Enterprise-grade Security**: Secure agent communication and data handling\n\n### `2` [Comprehensive Health Analytics][docs-health-analytics]\n\nRevolutionary health scoring system that transforms personal health data into actionable insights. Our WHO-standard algorithms provide personalized recommendations while maintaining the highest accuracy standards.\n\n**Health Scoring Components:**\n- **Exercise Health (0-100)**: Based on WHO recommendations (150 min/week moderate activity)\n- **Nutrition Health (0-100)**: Meal regularity, water intake (2000ml/day), nutrient balance\n- **Cycle Health (0-100)**: Cycle regularity (21-35 days), tracking completeness\n- **Mood Health (0-100)**: Emotional stability, symptom severity patterns\n- **Lifestyle Health (0-100)**: Sleep quality (7-9 hours), stress management\n- **Fertility Health (0-100)**: BBT patterns, cervical mucus tracking, ovulation indicators\n\n**Advanced Analytics:**\n- 📊 **Correlation Analysis**: Identify patterns between lifestyle factors and health outcomes\n- 🎯 **Predictive Insights**: AI-powered trend analysis and health forecasting\n- 📈 **Performance Optimization**: 90%+ Redis cache hit rate for instant data access\n- 🔄 **Real-time Synchronization**: Live updates across all health modules\n\n[![][back-to-top]](#readme-top)\n\n### `*` Additional Features\n\nBeyond the core AI agent system, FemTracker Agent includes:\n\n- [x] 💨 **Quick Setup**: Deploy in under 5 minutes with automated configuration\n- [x] 🌐 **Multi-language Support**: Comprehensive i18n with health terminology\n- [x] 🔒 **Privacy First**: All health data encrypted with military-grade security\n- [x] 💎 **Modern UI/UX**: Beautiful design with accessibility-first approach (WCAG 2.1)\n- [x] 🗣️ **Real-time AI Chat**: Conversational health assistance with natural language\n- [x] 📊 **Advanced Analytics**: Comprehensive health metrics and trend visualization\n- [x] 🔌 **Extensible Architecture**: Plugin system for custom health modules\n- [x] 📱 **Mobile Optimized**: Progressive Web App with native-like experience\n- [x] 🎯 **Personalized Recommendations**: AI-driven suggestions based on individual patterns\n- [x] 🏥 **Medical Standard Compliance**: WHO and FDA guideline adherence\n- [x] 📈 **Performance Monitoring**: Real-time system health and optimization metrics\n- [x] 🔄 **Data Export/Import**: Comprehensive health data portability\n\n\u003e ✨ Continuous feature development with monthly releases and community-driven improvements.\n\n\u003cdiv align=\"right\"\u003e\n\n[![][back-to-top]](#readme-top)\n\n\u003c/div\u003e\n\n## 🛠️ Tech Stack\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/nextdotjs\" width=\"48\" height=\"48\" alt=\"Next.js\" /\u003e\n        \u003cbr\u003eNext.js 15\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/react\" width=\"48\" height=\"48\" alt=\"React\" /\u003e\n        \u003cbr\u003eReact 19\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/typescript\" width=\"48\" height=\"48\" alt=\"TypeScript\" /\u003e\n        \u003cbr\u003eTypeScript 5\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/python\" width=\"48\" height=\"48\" alt=\"Python\" /\u003e\n        \u003cbr\u003ePython 3.12\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/langchain\" width=\"48\" height=\"48\" alt=\"LangGraph\" /\u003e\n        \u003cbr\u003eLangGraph\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/supabase\" width=\"48\" height=\"48\" alt=\"Supabase\" /\u003e\n        \u003cbr\u003eSupabase\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/redis\" width=\"48\" height=\"48\" alt=\"Redis\" /\u003e\n        \u003cbr\u003eRedis\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n**Frontend Stack:**\n- **Framework**: Next.js 15 with App Router for optimal performance\n- **Language**: TypeScript for comprehensive type safety\n- **Styling**: TailwindCSS + Custom Design System + Framer Motion\n- **State**: Custom hooks with database integration + React Query\n- **UI Components**: Radix UI + Accessibility-first components\n- **AI Integration**: CopilotKit for seamless conversational AI\n\n**Backend Stack:**\n- **AI Agents**: Python 3.12 + LangGraph for agent orchestration\n- **Database**: Supabase PostgreSQL with Row Level Security\n- **Cache**: Redis for performance optimization (90%+ hit rate)\n- **Authentication**: Supabase Auth with secure session management\n- **File Storage**: Vercel Blob for health data attachments\n- **AI Provider**: OpenAI GPT-4 for intelligent health insights\n\n**DevOps \u0026 Monitoring:**\n- **Deployment**: Vercel (Frontend) + LangGraph Platform (Agents)\n- **CI/CD**: GitHub Actions with automated testing\n- **Monitoring**: Real-time health analytics and performance metrics\n- **Testing**: Jest + React Testing Library + Playwright E2E\n\n\u003e [!TIP]\n\u003e Each technology was carefully selected for production readiness, scalability, and exceptional developer experience in the healthcare domain.\n\n## 🏗️ Architecture\n\n### Multi-Agent System Architecture\n\nThe platform employs a sophisticated multi-agent architecture where specialized AI agents handle different aspects of women's health, coordinated by an intelligent main coordinator:\n\n```mermaid\ngraph TB\n    subgraph \"User Interface Layer\"\n        A[Next.js Frontend] --\u003e B[CopilotKit Integration]\n        B --\u003e C[Real-time Chat Interface]\n        C --\u003e D[Health Dashboards]\n    end\n    \n    subgraph \"AI Agent Orchestration\"\n        E[Main Coordinator Agent] --\u003e F{Intelligent Routing}\n        F --\u003e G[Cycle Tracker Agent]\n        F --\u003e H[Fertility Tracker Agent]\n        F --\u003e I[Symptom Mood Agent]\n        F --\u003e J[Nutrition Guide Agent]\n        F --\u003e K[Exercise Coach Agent]\n        F --\u003e L[Lifestyle Manager Agent]\n        F --\u003e M[Health Insights Agent]\n        F --\u003e N[Recipe Agent]\n    end\n    \n    subgraph \"Data \u0026 Intelligence Layer\"\n        O[Supabase PostgreSQL] --\u003e P[Health Analytics Engine]\n        P --\u003e Q[WHO-Standard Scoring]\n        Q --\u003e R[Correlation Analysis]\n        R --\u003e S[Predictive Insights]\n    end\n    \n    subgraph \"Performance \u0026 Security\"\n        T[Redis Cache Layer]\n        U[Row Level Security]\n        V[Real-time Sync]\n        W[Data Encryption]\n    end\n    \n    D --\u003e E\n    G --\u003e O\n    H --\u003e O\n    I --\u003e O\n    J --\u003e O\n    K --\u003e O\n    L --\u003e O\n    M --\u003e O\n    N --\u003e O\n    \n    O --\u003e T\n    O --\u003e U\n    P --\u003e V\n    P --\u003e W\n```\n\n### Data Flow\n\n```mermaid\nsequenceDiagram\n    participant User as User\n    participant UI as Frontend\n    participant Coord as Main Coordinator\n    participant Agent as Specialized Agent\n    participant DB as Database\n    participant Cache as Redis Cache\n    participant Analytics as Health Analytics\n    \n    User-\u003e\u003eUI: Health Data Input\n    UI-\u003e\u003eCoord: Route Request\n    Coord-\u003e\u003eAgent: Delegate to Specialist\n    Agent-\u003e\u003eCache: Check Cache\n    alt Cache Hit\n        Cache-\u003e\u003eAgent: Return Cached Data\n    else Cache Miss\n        Agent-\u003e\u003eDB: Query Database\n        DB-\u003e\u003eAgent: Return Data\n        Agent-\u003e\u003eCache: Update Cache\n    end\n    Agent-\u003e\u003eAnalytics: Process Health Metrics\n    Analytics-\u003e\u003eAgent: Generate Insights\n    Agent-\u003e\u003eCoord: Return Response\n    Coord-\u003e\u003eUI: Unified Response\n    UI-\u003e\u003eUser: Real-time Updates\n```\n\n### Component Structure\n\nThe application follows a modular architecture with clear separation of concerns:\n\n```\nsrc/\n├── app/                    # Next.js App Router\n│   ├── (dashboard)/       # Protected dashboard routes\n│   │   ├── cycle-tracker/ # Menstrual cycle tracking\n│   │   ├── fertility/     # Fertility monitoring\n│   │   ├── nutrition/     # Nutrition guidance\n│   │   ├── exercise/      # Fitness tracking\n│   │   ├── lifestyle/     # Lifestyle management\n│   │   ├── insights/      # AI health insights\n│   │   └── recipe/        # AI recipe assistant\n│   ├── api/copilotkit/   # AI agent integration endpoint\n│   └── auth/             # Authentication flows\n├── components/           # Reusable UI components\n│   ├── home/            # Dashboard components\n│   ├── cycle/           # Cycle tracking UI\n│   ├── fertility/       # Fertility monitoring UI\n│   ├── insights/        # Analytics and charts\n│   ├── accessibility/   # WCAG 2.1 compliant components\n│   └── shared/          # Common components\n├── hooks/               # Custom React hooks\n│   ├── auth/           # Authentication hooks\n│   ├── cycle/          # Cycle management\n│   ├── fertility/      # Fertility tracking\n│   ├── insights/       # Analytics hooks\n│   └── copilot/        # AI integration hooks\n├── lib/                # Utility libraries\n│   ├── supabase/      # Database client\n│   ├── redis/         # Cache client\n│   └── utils/         # Helper functions\n├── types/              # TypeScript definitions\n└── constants/          # Application constants\n```\n\n## ⚡️ Performance\n\n\u003e [!NOTE]\n\u003e Complete performance reports and real-time monitoring available in production deployment\n\n### Performance Metrics\n\n**Key Performance Indicators:**\n- ⚡ **95+ Lighthouse Score** across all categories\n- 🚀 **\u003c 1s** Time to First Byte (TTFB)\n- 💨 **\u003c 100ms** API response times with Redis caching\n- 📊 **99.9%** uptime reliability\n- 🔄 **Real-time** data synchronization across all health modules\n- 🎯 **90%+ Cache Hit Rate** for optimal performance\n\n**Performance Optimizations:**\n- 🎯 **Smart Caching Strategy**: Redis-based caching with TTL optimization\n- 📦 **Code Splitting**: Automatic bundle optimization and lazy loading\n- 🖼️ **Image Optimization**: Next.js Image component with WebP support\n- 🔄 **Database Optimization**: Connection pooling and query optimization\n- 🤖 **Agent Performance**: Optimized LangGraph workflows for sub-second responses\n- 📱 **Mobile Performance**: Progressive Web App with offline capabilities\n\n**Caching Strategy:**\n```typescript\nconst cacheStrategies = {\n  healthMetrics: 1800,      // 30 minutes\n  recommendations: 3600,    // 1 hour  \n  trendAnalysis: 900,      // 15 minutes\n  userPreferences: 86400    // 24 hours\n};\n```\n\n\u003e [!NOTE]\n\u003e Performance metrics are continuously monitored using real-time analytics and automatically optimized based on usage patterns.\n\n\u003c!-- Links will be defined at the bottom of the file --\u003e\n[project-link]: https://femtracker-agent.vercel.app/\n[docs]: #\n[agent-docs]: #\n[docs-ai-agents]: #\n[docs-health-analytics]: #\n[demo-link]: https://femtracker-agent.vercel.app/\n[github-issues-link]: https://github.com/ChanMeng666/femtracker-agent/issues\n[github-release-link]: https://github.com/ChanMeng666/femtracker-agent/releases\n[github-contributors-link]: https://github.com/ChanMeng666/femtracker-agent/contributors\n[github-forks-link]: https://github.com/ChanMeng666/femtracker-agent/forks\n[github-stars-link]: https://github.com/ChanMeng666/femtracker-agent/stargazers\n[github-license-link]: https://github.com/ChanMeng666/femtracker-agent/blob/master/LICENSE\n[github-releasedate-link]: https://github.com/ChanMeng666/femtracker-agent/releases\n[github-action-test-link]: https://github.com/ChanMeng666/femtracker-agent/actions\n[vercel-link]: https://femtracker-agent.vercel.app/\n[discord-link]: #\n[back-to-top]: https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square\n\n\u003c!-- Shield Badges --\u003e\n[github-release-shield]: https://img.shields.io/github/v/release/ChanMeng666/femtracker-agent?color=369eff\u0026labelColor=black\u0026logo=github\u0026style=flat-square\n[vercel-shield]: https://img.shields.io/badge/vercel-online-55b467?labelColor=black\u0026logo=vercel\u0026style=flat-square\n[discord-shield]: https://img.shields.io/badge/discord-join-5865F2?labelColor=black\u0026logo=discord\u0026logoColor=white\u0026style=flat-square\n[github-action-test-shield]: https://img.shields.io/github/actions/workflow/status/ChanMeng666/femtracker-agent/test.yml?label=test\u0026labelColor=black\u0026logo=githubactions\u0026logoColor=white\u0026style=flat-square\n[github-releasedate-shield]: https://img.shields.io/github/release-date/ChanMeng666/femtracker-agent?labelColor=black\u0026style=flat-square\n[github-contributors-shield]: https://img.shields.io/github/contributors/ChanMeng666/femtracker-agent?color=c4f042\u0026labelColor=black\u0026style=flat-square\n[github-forks-shield]: https://img.shields.io/github/forks/ChanMeng666/femtracker-agent?color=8ae8ff\u0026labelColor=black\u0026style=flat-square\n[github-stars-shield]: https://img.shields.io/github/stars/ChanMeng666/femtracker-agent?color=ffcb47\u0026labelColor=black\u0026style=flat-square\n[github-issues-shield]: https://img.shields.io/github/issues/ChanMeng666/femtracker-agent?color=ff80eb\u0026labelColor=black\u0026style=flat-square\n[github-license-shield]: https://img.shields.io/badge/license-MIT-white?labelColor=black\u0026style=flat-square\n\n\u003c!-- Badge Variants --\u003e\n[demo-shield-badge]: https://img.shields.io/badge/TRY%20DEMO-ONLINE-55b467?labelColor=black\u0026logo=vercel\u0026style=for-the-badge\n[discord-shield-badge]: https://img.shields.io/badge/JOIN%20DISCORD-COMMUNITY-5865F2?labelColor=black\u0026logo=discord\u0026logoColor=white\u0026style=for-the-badge\n\n\u003c!-- Social Share Links --\u003e\n[share-x-link]: https://x.com/intent/tweet?hashtags=opensource,healthtech,AI\u0026text=Check%20out%20FemTracker%20Agent%20-%20AI-powered%20women%27s%20health%20companion\u0026url=https%3A%2F%2Fgithub.com%2FChanMeng666%2Ffemtracker-agent\n[share-telegram-link]: https://t.me/share/url?text=FemTracker%20Agent%20-%20AI-powered%20women%27s%20health%20companion\u0026url=https%3A%2F%2Fgithub.com%2FChanMeng666%2Ffemtracker-agent\n[share-whatsapp-link]: https://api.whatsapp.com/send?text=Check%20out%20FemTracker%20Agent%20-%20AI-powered%20women%27s%20health%20companion%20https%3A%2F%2Fgithub.com%2FChanMeng666%2Ffemtracker-agent\n[share-reddit-link]: https://www.reddit.com/submit?title=FemTracker%20Agent%20-%20AI-powered%20women%27s%20health%20companion\u0026url=https%3A%2F%2Fgithub.com%2FChanMeng666%2Ffemtracker-agent\n[share-linkedin-link]: https://linkedin.com/sharing/share-offsite/?url=https://github.com/ChanMeng666/femtracker-agent\n\n[share-x-shield]: https://img.shields.io/badge/-share%20on%20x-black?labelColor=black\u0026logo=x\u0026logoColor=white\u0026style=flat-square\n[share-telegram-shield]: https://img.shields.io/badge/-share%20on%20telegram-black?labelColor=black\u0026logo=telegram\u0026logoColor=white\u0026style=flat-square\n[share-whatsapp-shield]: https://img.shields.io/badge/-share%20on%20whatsapp-black?labelColor=black\u0026logo=whatsapp\u0026logoColor=white\u0026style=flat-square\n[share-reddit-shield]: https://img.shields.io/badge/-share%20on%20reddit-black?labelColor=black\u0026logo=reddit\u0026logoColor=white\u0026style=flat-square\n[share-linkedin-shield]: https://img.shields.io/badge/-share%20on%20linkedin-black?labelColor=black\u0026logo=linkedin\u0026logoColor=white\u0026style=flat-square\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n\u003e [!IMPORTANT]\n\u003e Ensure you have the following installed and configured:\n\n- **Node.js 18.0+** ([Download](https://nodejs.org/))\n- **Python 3.12+** for AI agent system ([Download](https://python.org/))\n- **npm/yarn/pnpm** package manager (pnpm recommended)\n- **Git** version control ([Download](https://git-scm.com/))\n- **Supabase Account** for database ([Sign up](https://supabase.com/))\n- **OpenAI API Key** for AI features ([Get API Key](https://platform.openai.com/))\n- **Redis** (optional) for enhanced performance ([Redis Cloud](https://redis.com/))\n\n### Quick Installation\n\n**1. Clone Repository**\n\n```bash\ngit clone https://github.com/ChanMeng666/femtracker-agent.git\ncd femtracker-agent\n```\n\n**2. Frontend Setup**\n\n```bash\n# Install frontend dependencies\nnpm install\n\n# Or using pnpm (recommended)\npnpm install\n\n# Or using yarn\nyarn install\n```\n\n**3. Backend AI Agent Setup**\n\n```bash\n# Navigate to agent directory\ncd agent\n\n# Create virtual environment\npython -m venv venv\n\n# Activate virtual environment\n# Windows:\nvenv\\Scripts\\activate\n# macOS/Linux:\nsource venv/bin/activate\n\n# Install Python dependencies\npip install -r requirements.txt\n```\n\n**4. Database Setup**\n\nExecute the SQL files in your Supabase SQL Editor in the following order:\n\n```sql\n-- 1. Core database schema\n-- Run: database/1-database-setup.sql\n\n-- 2. Fix RLS policies (if needed)\n-- Run: database/2-database-fix.sql\n\n-- 3. Fertility tracking tables\n-- Run: database/6-fertility-tables.sql\n\n-- 4. Recipe management tables  \n-- Run: database/7-recipe-tables.sql\n\n-- 5. Extended health analytics\n-- Run: database/4-database-schema-extension.sql\n\n-- 6. Nutrition preferences\n-- Run: database/10-nutrition-focus-table.sql\n```\n\n### Environment Setup\n\n**Frontend (.env.local):**\n\n```bash\n# OpenAI Configuration\nOPENAI_API_KEY=your_openai_api_key_here\n\n# Supabase Configuration\nNEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url\nNEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key\nSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key\n\n# CopilotKit Agent Configuration\nNEXT_PUBLIC_COPILOTKIT_AGENT_NAME=main_coordinator\nNEXT_PUBLIC_COPILOTKIT_AGENT_DESCRIPTION=\"AI health companion with specialized agents for women's health tracking\"\n\n# Optional: Redis Configuration for Performance\nREDIS_URL=your_redis_connection_string\n\n# Optional: Vercel Blob Storage\nBLOB_READ_WRITE_TOKEN=your_blob_storage_token\n\n# Optional: LangGraph Platform\nLANGGRAPH_DEPLOYMENT_URL=your_langgraph_deployment_url\nLANGSMITH_API_KEY=your_langsmith_api_key\n```\n\n**Backend (agent/.env):**\n\n```bash\n# OpenAI Configuration (Required)\nOPENAI_API_KEY=your_openai_api_key_here\n\n# Optional: LangGraph Platform for Production\nLANGGRAPH_DEPLOYMENT_URL=your_langgraph_deployment_url\nLANGSMITH_API_KEY=your_langsmith_api_key\n```\n\n\u003e [!TIP]\n\u003e Use `openssl rand -base64 32` to generate secure random secrets for production deployment.\n\n### Development Mode\n\n**Terminal 1 - Start AI Agent System:**\n```bash\ncd agent\n# Activate virtual environment\nvenv\\Scripts\\activate  # Windows\n# source venv/bin/activate  # macOS/Linux\n\n# Start LangGraph development server\nlanggraph dev\n```\n\n**Terminal 2 - Start Frontend:**\n```bash\n# Start Next.js development server\nnpm run dev\n# or\npnpm dev\n# or\nyarn dev\n```\n\n**5. Access the Application:**\n\n- **Frontend Application**: http://localhost:3000\n- **AI Agent System**: http://localhost:2024\n- **Health Dashboard**: http://localhost:3000/\n- **Cycle Tracker**: http://localhost:3000/cycle-tracker\n- **AI Recipe Assistant**: http://localhost:3000/recipe\n\n🎉 **Success!** Your AI-powered health companion is now running locally.\n\n## 🛳 Deployment\n\n\u003e [!IMPORTANT]\n\u003e Choose the deployment strategy that best fits your needs. Cloud deployment is recommended for production applications with full AI agent functionality.\n\n### `A` Cloud Deployment\n\n**Vercel (Frontend - Recommended)**\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FChanMeng666%2Ffemtracker-agent)\n\n**Manual Deployment:**\n\n```bash\n# Install Vercel CLI\nnpm i -g vercel\n\n# Deploy to production\nvercel --prod\n```\n\n**LangGraph Platform (AI Agents - Recommended)**\n\n```bash\n# Navigate to agent directory\ncd agent\n\n# Deploy to LangGraph Platform\nlanggraph up\n```\n\n### `B` Docker Deployment\n\n**Frontend Docker:**\n\n```dockerfile\nFROM node:18-alpine AS deps\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --only=production\n\nFROM node:18-alpine AS builder\nWORKDIR /app\nCOPY . .\nCOPY --from=deps /app/node_modules ./node_modules\nRUN npm run build\n\nFROM node:18-alpine AS runner\nWORKDIR /app\nENV NODE_ENV production\nCOPY --from=builder /app/public ./public\nCOPY --from=builder /app/.next/standalone ./\nCOPY --from=builder /app/.next/static ./.next/static\n\nEXPOSE 3000\nCMD [\"node\", \"server.js\"]\n```\n\n**AI Agent System Docker:**\n\n```dockerfile\nFROM python:3.12-slim\nWORKDIR /app\nCOPY agent/ .\nRUN pip install -r requirements.txt\nEXPOSE 2024\nCMD [\"langgraph\", \"dev\", \"--host\", \"0.0.0.0\", \"--port\", \"2024\"]\n```\n\n**Docker Compose:**\n\n```yaml\nversion: '3.8'\nservices:\n  frontend:\n    build: .\n    ports:\n      - \"3000:3000\"\n    environment:\n      - NEXT_PUBLIC_SUPABASE_URL=${SUPABASE_URL}\n      - OPENAI_API_KEY=${OPENAI_API_KEY}\n    depends_on:\n      - agents\n  \n  agents:\n    build: ./agent\n    ports:\n      - \"2024:2024\"\n    environment:\n      - OPENAI_API_KEY=${OPENAI_API_KEY}\n    volumes:\n      - ./agent:/app\n  \n  redis:\n    image: redis:7-alpine\n    ports:\n      - \"6379:6379\"\n    volumes:\n      - redis_data:/data\n\nvolumes:\n  redis_data:\n```\n\n### `C` Environment Variables\n\n\u003e [!WARNING]\n\u003e Never commit sensitive environment variables to version control. Use secure secret management in production.\n\n| Variable | Description | Required | Default | Example |\n|----------|-------------|----------|---------|---------|\n| `OPENAI_API_KEY` | OpenAI API key for AI agents | ✅ | - | `sk-xxxxxxxxxxxxx` |\n| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL | ✅ | - | `https://xxx.supabase.co` |\n| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase anonymous key | ✅ | - | `eyJhbGciOiJIUzI1NiIs...` |\n| `SUPABASE_SERVICE_ROLE_KEY` | Supabase service role key | ✅ | - | `eyJhbGciOiJIUzI1NiIs...` |\n| `REDIS_URL` | Redis connection string | 🔶 | - | `redis://localhost:6379` |\n| `LANGGRAPH_DEPLOYMENT_URL` | LangGraph platform URL | 🔶 | - | `https://xxx.langraph.app` |\n| `LANGSMITH_API_KEY` | LangSmith API key | 🔶 | - | `ls__xxxxxxxxxxxxxxxx` |\n| `BLOB_READ_WRITE_TOKEN` | Vercel Blob storage token | 🔶 | - | `vercel_blob_rw_xxx` |\n\n\u003e [!NOTE]\n\u003e ✅ Required, 🔶 Optional\n\n**Security Best Practices:**\n- 🔐 Use environment-specific configuration files\n- 🚫 Never hardcode secrets in source code\n- 🔄 Rotate API keys regularly (recommended: monthly)\n- 🛡️ Use secret management services in production\n- 📝 Implement audit logging for sensitive operations\n\n## 📖 Usage Guide\n\n### Basic Usage\n\n**Getting Started with FemTracker Agent:**\n\n1. **Create Account**: Sign up using email or social authentication\n2. **Complete Health Profile**: Set up your personal health preferences and goals\n3. **Start Tracking**: Begin with cycle tracking and gradually add other health modules\n4. **Interact with AI**: Use natural language to ask health questions and get personalized insights\n5. **Monitor Progress**: View your health dashboard and analytics for comprehensive insights\n\n**Quick Actions:**\n\n```bash\n# Health data input via API (for integrations)\ncurl -X POST https://your-app.vercel.app/api/health/cycle \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"date\": \"2024-01-15\",\n    \"flow_intensity\": \"Medium\",\n    \"symptoms\": [\"cramps\", \"fatigue\"]\n  }'\n\n# Get health insights\ncurl -X GET https://your-app.vercel.app/api/health/insights \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n### AI Agent System\n\n**Conversational Health Assistance:**\n\nThe AI agent system provides natural language interaction for all health-related queries:\n\n```\nUser: \"I'm feeling tired and have cramps today, what should I do?\"\n\nAI Response: Based on your symptoms and current cycle phase (Day 2), here are personalized recommendations:\n• Rest: Consider light stretching or gentle yoga\n• Nutrition: Increase iron-rich foods and stay hydrated\n• Pain relief: Apply heat therapy or try herbal teas\n• Tracking: I've logged your symptoms for pattern analysis\n```\n\n**Specialized Agent Functions:**\n\n- **Cycle Tracker**: \"When is my next period?\" / \"Track today's flow as heavy\"\n- **Fertility Agent**: \"Am I in my fertile window?\" / \"Log BBT temperature 98.6°F\"\n- **Nutrition Guide**: \"What should I eat during my period?\" / \"Track today's meals\"\n- **Exercise Coach**: \"What exercises are best for today?\" / \"Log 30-minute walk\"\n- **Lifestyle Manager**: \"I slept 6 hours last night\" / \"My stress level is high today\"\n- **Health Insights**: \"Show me my health trends\" / \"What patterns do you notice?\"\n\n### Health Scoring System\n\n**WHO-Standard Health Metrics:**\n\nThe system calculates comprehensive health scores based on medical standards:\n\n```typescript\ninterface HealthScore {\n  overall: number;        // 0-100 composite score\n  cycleHealth: number;    // Cycle regularity and tracking\n  nutritionScore: number; // Dietary habits and hydration\n  exerciseScore: number;  // Physical activity levels\n  fertilityScore: number; // Reproductive health indicators\n  lifestyleScore: number; // Sleep and stress management\n  symptomsScore: number;  // Symptom patterns and severity\n}\n```\n\n**Scoring Algorithms:**\n\n- **Exercise Health**: Based on WHO recommendation of 150 minutes/week moderate activity\n- **Nutrition Health**: Evaluates meal regularity, water intake (2000ml/day), nutrient balance\n- **Cycle Health**: Assesses cycle regularity (21-35 days), tracking completeness\n- **Mood Health**: Analyzes emotional stability and symptom severity patterns\n- **Lifestyle Health**: Considers sleep quality (7-9 hours), stress management\n- **Fertility Health**: Evaluates BBT patterns, cervical mucus tracking, ovulation indicators\n\n## 🤖 AI Agents\n\nOur sophisticated multi-agent system features 8 specialized AI agents, each optimized for specific health domains:\n\n| Agent | Purpose | Key Capabilities | Example Interactions |\n|-------|---------|------------------|---------------------|\n| **Main Coordinator** | Intelligent routing and orchestration | Request analysis, agent selection, response coordination | \"Help me with my health today\" |\n| **Cycle Tracker** | Menstrual cycle management | Period prediction, flow tracking, cycle analysis | \"Log my period started today\" |\n| **Fertility Tracker** | Ovulation and conception guidance | BBT tracking, fertile window prediction, conception planning | \"Am I ovulating today?\" |\n| **Symptom Mood** | Symptoms and emotional health | Pattern recognition, mood analysis, trigger identification | \"I'm feeling anxious and bloated\" |\n| **Nutrition Guide** | Dietary guidance and planning | Meal recommendations, nutrient analysis, supplement advice | \"What should I eat for iron?\" |\n| **Exercise Coach** | Fitness and workout optimization | Cycle-aware workouts, activity tracking, performance analysis | \"Best exercises for period pain?\" |\n| **Lifestyle Manager** | Sleep and stress management | Sleep optimization, stress reduction, habit tracking | \"Help me sleep better\" |\n| **Health Insights** | Comprehensive analytics | Trend analysis, correlation detection, predictive insights | \"Show me my health patterns\" |\n\n**Agent Coordination Example:**\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant MainCoord as Main Coordinator\n    participant CycleAgent as Cycle Tracker\n    participant NutritionAgent as Nutrition Guide\n    participant InsightsAgent as Health Insights\n    \n    User-\u003e\u003eMainCoord: \"I'm on day 2 of my period and feeling low energy\"\n    MainCoord-\u003e\u003eCycleAgent: Analyze cycle context\n    CycleAgent-\u003e\u003eMainCoord: \"Day 2, menstrual phase, common low energy\"\n    MainCoord-\u003e\u003eNutritionAgent: Get nutrition recommendations\n    NutritionAgent-\u003e\u003eMainCoord: \"Iron-rich foods, hydration, comfort foods\"\n    MainCoord-\u003e\u003eInsightsAgent: Check historical patterns\n    InsightsAgent-\u003e\u003eMainCoord: \"User typically experiences this, suggest rest\"\n    MainCoord-\u003e\u003eUser: Comprehensive response with cycle context, nutrition advice, and personalized insights\n```\n\n## 📦 Database Schema\n\nFemTracker Agent uses a comprehensive PostgreSQL database with 15+ tables designed for women's health tracking:\n\n**Core Tables:**\n- `profiles` - User profiles and basic information\n- `user_preferences` - Personalized settings and configurations\n- `menstrual_cycles` - Cycle tracking with start/end dates and patterns\n- `period_days` - Daily flow intensity and period-specific data\n- `symptoms` - Comprehensive symptom tracking with severity\n- `moods` - Emotional health and mood pattern analysis\n\n**Advanced Health Tracking:**\n- `fertility_records` - BBT, cervical mucus, ovulation tests\n- `exercises` - Activity tracking with intensity and duration\n- `meals` \u0026 `water_intake` - Comprehensive nutrition monitoring\n- `lifestyle_entries` - Sleep quality, stress levels, weight tracking\n- `health_insights` - AI-generated insights and recommendations\n\n**Analytics and Intelligence:**\n- `health_overview` - Calculated health scores and metrics\n- `ai_insights` - Advanced AI-generated health insights\n- `correlation_analyses` - Pattern recognition and health correlations\n- `notifications` - Smart notification system\n\n**Security Features:**\n- Row Level Security (RLS) on all tables\n- User-specific data isolation\n- Encrypted sensitive health information\n- GDPR-compliant data handling\n\n**Database Performance:**\n- Optimized indexes for health query patterns\n- Redis caching for frequently accessed data\n- Real-time synchronization across all modules\n- Automated backup and recovery systems\n\n## ⌨️ Development\n\n### Local Development\n\n**Complete Development Setup:**\n\n```bash\n# 1. Clone and setup repository\ngit clone https://github.com/ChanMeng666/femtracker-agent.git\ncd femtracker-agent\n\n# 2. Frontend setup\nnpm install\ncp .env.example .env.local\n# Edit .env.local with your configuration\n\n# 3. Backend setup\ncd agent\npython -m venv venv\nsource venv/bin/activate  # or venv\\Scripts\\activate on Windows\npip install -r requirements.txt\ncp .env.example .env\n# Edit .env with your configuration\n\n# 4. Database setup\n# Run SQL files in Supabase dashboard in order\n\n# 5. Start development servers\n# Terminal 1:\ncd agent \u0026\u0026 langgraph dev\n\n# Terminal 2:\nnpm run dev\n```\n\n**Development Scripts:**\n\n```bash\n# Frontend Development\nnpm run dev          # Start development server\nnpm run build        # Production build\nnpm run start        # Start production build\nnpm run lint         # ESLint checking\nnpm run type-check   # TypeScript validation\n\n# Backend Development\nlanggraph dev        # Start agent development server\nlanggraph up         # Deploy to LangGraph platform\npython -m pytest    # Run agent tests\n\n# Database\nnpx supabase start   # Start local Supabase\nnpx supabase db reset # Reset database\nnpx supabase db push # Push schema changes\n```\n\n### Adding New Agents\n\n**1. Create Agent Structure:**\n\n```bash\n# Create new agent directory\nmkdir agent/new_health_agent\ncd agent/new_health_agent\ntouch __init__.py agent.py\n```\n\n**2. Agent Implementation:**\n\n```python\n# agent/new_health_agent/agent.py\nfrom typing import Dict, Any\nfrom langgraph.graph import StateGraph, START, END\nfrom copilotkit import CopilotKitState\nfrom copilotkit.langgraph import copilotkit_emit_state\n\nclass AgentState(CopilotKitState):\n    health_data: Dict[str, Any] = {}\n\nasync def process_health_data(state: AgentState, config):\n    \"\"\"Process health-specific requests\"\"\"\n    # Implement agent logic\n    await copilotkit_emit_state(config, state)\n    return state\n\n# Create workflow\nworkflow = StateGraph(AgentState)\nworkflow.add_node(\"process\", process_health_data)\nworkflow.add_edge(START, \"process\")\nworkflow.add_edge(\"process\", END)\n\ngraph = workflow.compile()\n```\n\n**3. Register Agent:**\n\n```json\n// agent/langgraph.json\n{\n  \"graphs\": {\n    \"new_health_agent\": \"./new_health_agent/agent.py:graph\"\n  }\n}\n```\n\n**4. Frontend Integration:**\n\n```typescript\n// src/app/api/copilotkit/route.ts\n{\n  name: \"new_health_agent\",\n  description: \"Specialized agent for new health domain\"\n}\n```\n\n### Creating Custom Health Modules\n\n**1. Frontend Module Structure:**\n\n```bash\n# Create module components\nmkdir src/components/new-module\nmkdir src/app/new-module\nmkdir src/hooks/new-module\ntouch src/types/new-module.ts\ntouch src/constants/new-module.ts\n```\n\n**2. Database Schema:**\n\n```sql\n-- Add to database/new-module-schema.sql\nCREATE TABLE new_health_data (\n  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),\n  user_id UUID REFERENCES profiles(id) ON DELETE CASCADE,\n  date DATE NOT NULL,\n  specific_data JSONB NOT NULL,\n  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()\n);\n\n-- Enable RLS\nALTER TABLE new_health_data ENABLE ROW LEVEL SECURITY;\nCREATE POLICY \"Users manage own data\" ON new_health_data\n  FOR ALL USING (auth.uid() = user_id);\n```\n\n**3. Custom Hooks:**\n\n```typescript\n// src/hooks/new-module/useNewModule.ts\nexport const useNewModule = () =\u003e {\n  const [data, setData] = useState(null);\n  const [loading, setLoading] = useState(false);\n\n  const addData = async (newData: any) =\u003e {\n    setLoading(true);\n    try {\n      // Implement data operations\n      const result = await supabase\n        .from('new_health_data')\n        .insert(newData);\n      \n      if (result.error) throw result.error;\n      setData(result.data);\n    } catch (error) {\n      console.error('Error:', error);\n    } finally {\n      setLoading(false);\n    }\n  };\n\n  return { data, loading, addData };\n};\n```\n\n**4. Integration with Health Scoring:**\n\n```typescript\n// src/utils/shared/healthScoreCalculator.ts\nexport const calculateNewModuleScore = (data: any[]): number =\u003e {\n  // Implement scoring algorithm based on health standards\n  // Return score 0-100\n};\n```\n\n## 🤝 Contributing\n\nWe welcome contributions to FemTracker Agent! Here's how you can help improve women's health technology:\n\n**Development Process:**\n\n1. **Fork and Clone:**\n```bash\ngit clone https://github.com/ChanMeng666/femtracker-agent.git\ncd femtracker-agent\n```\n\n2. **Create Feature Branch:**\n```bash\ngit checkout -b feature/amazing-health-feature\n```\n\n3. **Development Guidelines:**\n- ✅ Follow TypeScript best practices and strict type checking\n- ✅ Add comprehensive tests for new health modules\n- ✅ Include JSDoc documentation for all public APIs\n- ✅ Follow accessibility guidelines (WCAG 2.1 AA compliance)\n- ✅ Add proper error handling and user feedback\n- ✅ Ensure medical accuracy and cite health standards\n- ✅ Test across different health scenarios and edge cases\n\n4. **Testing Requirements:**\n```bash\n# Frontend testing\nnpm run test              # Unit tests\nnpm run test:e2e         # End-to-end tests\nnpm run test:accessibility # Accessibility testing\n\n# Backend testing  \npython -m pytest        # Agent system tests\npython -m pytest --cov  # Coverage report\n```\n\n5. **Submit Pull Request:**\n- Provide clear description of health improvements\n- Include screenshots for UI changes\n- Reference related health issues or user feedback\n- Ensure all CI checks pass\n- Add documentation for new health features\n\n**Contribution Areas:**\n\n- 🐛 **Bug Reports**: Health tracking accuracy, AI agent responses\n- 💡 **Feature Requests**: New health modules, AI agent capabilities  \n- 📚 **Documentation**: Health guides, API documentation, user tutorials\n- 🎨 **UI/UX Improvements**: Accessibility, mobile responsiveness\n- 🔬 **Health Algorithm Enhancement**: WHO standard compliance, accuracy\n- 🤖 **AI Agent Development**: New specialized agents, improved responses\n- 🌐 **Internationalization**: Multi-language health terminology\n- 🔒 **Security**: Health data protection, privacy enhancements\n\n**Code Review Process:**\n- Health data accuracy verification\n- Medical terminology validation  \n- User experience testing\n- Performance impact assessment\n- Security and privacy review\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n**Open Source Benefits:**\n- ✅ Commercial use allowed\n- ✅ Modification allowed  \n- ✅ Distribution allowed\n- ✅ Private use allowed\n- ✅ Patent use protection\n\n**Health Data Commitment:**\n- 🔒 User health data remains private and secure\n- 📋 Compliance with healthcare privacy standards\n- 🌍 Open-source algorithms for transparency\n- 🤝 Community-driven health improvements\n\n## 👥 Team\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/ChanMeng666\"\u003e\n          \u003cimg src=\"https://github.com/ChanMeng666.png?size=100\" width=\"100px;\" alt=\"Chan Meng\"/\u003e\n          \u003cbr /\u003e\n          \u003csub\u003e\u003cb\u003eChan Meng\u003c/b\u003e\u003c/sub\u003e\n        \u003c/a\u003e\n        \u003cbr /\u003e\n        \u003csmall\u003eCreator \u0026 Lead Developer\u003c/small\u003e\n        \u003cbr /\u003e\n        \u003csmall\u003eAI Agent Architecture • Health Analytics • Frontend Development\u003c/small\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n## 🙋‍♀️ Author\n\n**Chan Meng**\n- \u003cimg src=\"https://cdn.simpleicons.org/linkedin/0A66C2\" width=\"16\" height=\"16\"\u003e LinkedIn: [chanmeng666](https://www.linkedin.com/in/chanmeng666/)\n- \u003cimg src=\"https://cdn.simpleicons.org/github/181717\" width=\"16\" height=\"16\"\u003e GitHub: [ChanMeng666](https://github.com/ChanMeng666)\n- \u003cimg src=\"https://cdn.simpleicons.org/gmail/EA4335\" width=\"16\" height=\"16\"\u003e Email: [chanmeng.dev@gmail.com](mailto:chanmeng.dev@gmail.com)\n- \u003cimg src=\"https://cdn.simpleicons.org/internetexplorer/0078D4\" width=\"16\" height=\"16\"\u003e Portfolio: [chanmeng.org](https://chanmeng.org/)\n\n**Specializations:**\n- 🤖 AI Agent System Architecture\n- 💊 Healthcare Technology Development  \n- 📊 Health Analytics and WHO Standard Implementation\n- 🌸 Women's Health Technology Innovation\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003cstrong\u003e🌸 Empowering Women's Health Through AI Technology 💖\u003c/strong\u003e\n\u003cbr/\u003e\n\u003cem\u003ePioneering the future of personalized healthcare with intelligent agent systems\u003c/em\u003e\n\u003cbr/\u003e\u003cbr/\u003e\n\n⭐ **Star us on GitHub** • 📖 **Read the Documentation** • 🐛 **Report Issues** • 💡 **Request Features** • 🤝 **Contribute to Women's Health Tech**\n\n\u003cbr/\u003e\u003cbr/\u003e\n\n**Made with ❤️ by the FemTracker Agent team**\n\n\u003cimg src=\"https://img.shields.io/github/stars/ChanMeng666/femtracker-agent?style=social\" alt=\"GitHub stars\"\u003e\n\u003cimg src=\"https://img.shields.io/github/forks/ChanMeng666/femtracker-agent?style=social\" alt=\"GitHub forks\"\u003e\n\u003cimg src=\"https://img.shields.io/github/watchers/ChanMeng666/femtracker-agent?style=social\" alt=\"GitHub watchers\"\u003e\n\n\u003c/div\u003e\n\u003c/rewritten_file\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanmeng666%2Ffemtracker-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchanmeng666%2Ffemtracker-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanmeng666%2Ffemtracker-agent/lists"}