Cross-platform Personal Health Tracker with AI Coach
FitCoach is a comprehensive cross-platform health tracking system with native clients for Desktop (Linux/Windows/macOS) and Mobile (iOS/Android). All data is stored on a secure server with FastAPI backend and PostgreSQL database. The application enables tracking of daily habits, health metrics, and provides AI-powered coaching insights using LangChain + LLM.
Project Status: ✅ Backend MVP complete | ✅ Mobile app production ready | 🔨 Desktop 95% complete
┌──────────────────────────────────┐
│ Desktop App (Electron + React) │
│ - LocalStorage cache │
│ - REST API → FastAPI │
│ - AI Agents UI (Chat, Coaches) │
└────────────┬─────────────────────┘
│
┌────────────┼─────────────────────┐
│ Mobile App (React Native) ✅ │
│ - iOS 15+ / Android 8+ │
│ - SecureStore (tokens) │
│ - Offline support │
│ - Multi-language (EN/RU/CZ) │
└────────────┬─────────────────────┘
│ HTTPS / JWT
┌────────────▼─────────────────────┐
│ FastAPI Backend (Python) │
│ - JWT Authentication │
│ - Security Headers ✅ │
│ - AI Agents (LangChain + LLM) ✅│
└────────────┬─────────────────────┘
│
┌────────────▼─────────────────────┐
│ PostgreSQL Database │
└──────────────────────────────────┘
- Daily Tracking Card - Date, tags, wellness score, effort rating
- Weight Tracking - Daily weight logging with trend visualization
- Nutrition Logging - Meals with macronutrients, calories, categories
- Exercise Tracking - Workouts with duration, intensity, heart rate
- Water Intake - Visual hydration monitoring (goal: 2.5-3L)
- Sleep Tracking - Duration, quality rating, sleep phases
- Mood Tracking - 1-5 scale with tags (stress, focus, energy)
- Notes - Markdown editor for daily reflections
- AI Agents System ✅ - 5 specialized AI coaches powered by LLM:
- Vision Agent - Meal photo recognition with Gemini/GPT-4 Vision
- Daily Summary - Personalized daily insights and recommendations
- Chatbot - Conversational fitness assistant
- Nutrition Coach - Context-aware nutrition advice
- Workout Coach - Personalized training guidance
- Weight, distance, calories, water, sleep, effort graphs
- Weekly/monthly aggregations
- Trend analysis and progress visualization
- JWT-based authentication (access + refresh tokens)
- Password hashing with bcrypt (12 rounds)
- User data isolation
- Comprehensive security headers (XSS, CSP, HSTS)
- Restricted CORS configuration
- Secure token storage (SecureStore on mobile)
- No hardcoded secrets (all via .env)
- See SECURITY.md for full details
- Backend: Python 3.11+, PostgreSQL 15+, Docker & Docker Compose
- Desktop: Node.js 18+, npm 9+
-
Clone the repository
git clone <repository-url> cd fit-coach
-
Backend Setup
cd backend python3 -m venv venv source venv/bin/activate # Linux/Mac pip install -r requirements.txt cp .env.example .env # Configure your settings docker-compose up -d # Start PostgreSQL alembic upgrade head # Run migrations python main.py # Start server at http://localhost:8001
-
Desktop Setup
cd desktop npm install npm run dev # Start at http://localhost:5173
For detailed setup instructions, see SETUP.md.
fit-coach/
├── backend/ # FastAPI REST API
│ ├── app/
│ │ ├── api/ # API endpoints
│ │ ├── core/ # Config, security, database
│ │ ├── models/ # SQLAlchemy models
│ │ ├── schemas/ # Pydantic schemas
│ │ └── services/ # Business logic
│ ├── alembic/ # Database migrations
│ ├── tests/ # Pytest test suite
│ └── README.md # Backend documentation
│
├── desktop/ # Electron + React client
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── pages/ # Page components
│ │ ├── services/ # API client
│ │ ├── store/ # Zustand state management
│ │ └── types/ # TypeScript types
│ ├── electron/ # Electron main process
│ └── README.md # Desktop documentation
│
├── mobile/ # React Native app (iOS + Android) ✅
│ ├── src/
│ │ ├── screens/ # App screens
│ │ ├── navigation/ # Navigation setup
│ │ ├── services/ # API client
│ │ ├── store/ # Zustand state
│ │ └── i18n/ # Multi-language
│ └── README.md # Mobile documentation
│
└── docs/ # Project documentation
├── README.md # Documentation index
├── architecture-decisions.md # ADRs
├── api-specification.md # OpenAPI 3.0 spec
├── database-schema.md # Database design
├── implementation-plan.md # Task breakdown (550+ tasks)
└── llm-progress.md # AI features tracking
| Component | Technology | Purpose |
|---|---|---|
| Framework | FastAPI | REST API framework |
| Database | PostgreSQL 15+ | Relational data storage |
| ORM | SQLAlchemy 2.0 | Database abstraction |
| Migrations | Alembic | Schema version control |
| Auth | JWT (python-jose) | Stateless authentication |
| Validation | Pydantic v2 | Request/response validation |
| Testing | Pytest | Unit & integration tests |
| Component | Technology | Purpose |
|---|---|---|
| Framework | Electron 39 | Cross-platform desktop app |
| UI Framework | React 19 | Component-based UI |
| Language | TypeScript 5.8 | Type-safe development |
| Styling | TailwindCSS 3.4 | Utility-first CSS |
| Components | shadcn/ui | High-quality UI components |
| State | Zustand 5.0 | Lightweight state management |
| Router | React Router 7 | Client-side routing |
| Charts | Recharts | Data visualization |
| HTTP Client | Axios | API communication |
| Component | Technology | Purpose |
|---|---|---|
| Framework | React Native 0.73 + Expo | Cross-platform mobile |
| Language | TypeScript 5.8 | Type-safe development |
| Navigation | React Navigation 6 | Native navigation |
| UI Components | React Native Paper | Material Design |
| State | Zustand 5.0 | State management |
| Storage | Expo SecureStore | Secure token storage |
| Charts | react-native-chart-kit | Data visualization |
| i18n | i18next | Multi-language (EN/RU/CZ) |
- SETUP.md - Comprehensive setup guide for all platforms
- project.md - Complete technical specification (Russian)
- docs/ - Detailed documentation
- Architecture Decisions - ADRs explaining key choices
- API Specification - OpenAPI 3.0 REST API docs
- Database Schema - Database design & relationships
- Implementation Plan - 550+ atomic tasks breakdown
- AI_AGENTS_COMPLETE.md - Complete AI Agents system overview
- backend/AGENTS_API_DOCUMENTATION.md - Full API reference for all agents
- VISION_AGENT_MVP_COMPLETE.md - Vision Agent (meal photo recognition)
- VISION_AGENT_SETUP.md - Gemini Vision API setup guide
- docs/WEIGHT_TRACKING.md - Daily weight tracking implementation
- docs/I18N_MULTILANGUAGE.md - Multi-language support (EN/RU/CZ)
- docs/DESKTOP_NOTIFICATIONS.md - Native desktop notifications
- mobile/README.md - Complete mobile app documentation
- docs/MOBILE_APPS_PLAN.md - Development plan and architecture
- SECURITY.md - Security policy and best practices
- backend/README.md - Backend API documentation
- desktop/README.md - Desktop client documentation
- desktop/ELECTRON_MIGRATION.md - Tauri to Electron migration details
cd backend
source venv/bin/activate
pytest # Run all tests (18/18 passing)
pytest --cov=app tests/ # With coverage reportSee backend/TEST_REPORT.md for detailed test results.
cd desktop
npm test # Run tests (when implemented)- Backend MVP with core models (User, Day, Meal, Exercise, Water, Sleep, Mood)
- JWT authentication with refresh tokens
- Database schema & migrations
- API documentation (Swagger/OpenAPI)
- Backend test suite (18/18 passing)
- Desktop foundation (Electron + React + TypeScript)
- State management & API integration
- Tauri → Electron migration for better performance
- AI Agents System (5 agents):
- Vision Agent - Meal photo recognition (Gemini/GPT-4 Vision)
- Daily Summary Agent - Personalized daily insights
- Chatbot Agent - Conversational fitness assistant
- Nutrition Coach - Context-aware nutrition advice
- Workout Coach - Personalized training guidance
- Frontend UI for all AI agents (ChatbotDialog, CoachDialog, AISummarySection)
- Complete API documentation and integration tests
- Desktop UI (95% complete):
- Authentication pages (Login, Register)
- Calendar view with monthly grid
- Day view with 7 tabs (Overview, Meals, Exercise, Water, Sleep, Mood, Notes)
- Statistics page with charts
- Profile & Settings page
- Daily weight tracking with trend visualization
- Multi-language support (EN/RU/CZ) with i18next
- Desktop notifications with configurable daily reminders
- Mobile App (React Native - Production Ready) ✅:
- iOS 15+ and Android 8+ support
- Authentication (Login/Register) with JWT
- Calendar view with day markers
- Day screen with 7 tabs (full tracking)
- Statistics screen with charts (Week/Month)
- AI Agents (Chatbot, Vision, Coaches)
- Profile & Settings
- Multi-language (EN/RU/CZ)
- Secure token storage (SecureStore)
- Security Hardening ✅:
- Removed hardcoded secrets
- Added comprehensive security headers
- Restricted CORS configuration
- Created security documentation (SECURITY.md)
- Desktop UI polish (5% remaining)
- Response streaming for AI agents
- Multi-agent coordination
- Voice input/output for agents
- 7-day meal plan generation
- Training program generation (12-week programs)
- Wearables integration (Garmin, Fitbit)
- Data export/import (JSON)
- Dark mode theme
- Push notifications for mobile apps
Contributions are welcome! Please see CONTRIBUTING.md for:
- Git workflow & branching strategy
- Conventional commit guidelines
- Code style standards
- Testing requirements
- Pull request process
This project is licensed under the MIT License - see the LICENSE file for details.
- Backend API: http://localhost:8001
- API Docs: http://localhost:8001/docs (Swagger UI)
- Desktop App: http://localhost:5173 (dev server)
- Issue Tracker: GitHub Issues
The project recently migrated from Tauri to Electron due to performance issues with complex SVG rendering (7+ Recharts charts) in WebKitGTK on Linux. Electron provides consistent Chromium-based rendering across all platforms with hardware acceleration. See desktop/ELECTRON_MIGRATION.md for details.
FastAPI provides automatic API documentation, excellent performance, native async support, and Pydantic validation out of the box - perfect for building modern REST APIs.
PostgreSQL offers robust JSONB support for nested data structures, excellent performance, and is free for enterprise use. Essential for storing complex health tracking data with flexible schemas.
For questions or support, please open an issue on GitHub.
Built with ❤️ for better health tracking