Astrology App

A comprehensive astrology application featuring accurate birth chart calculations, interactive visualizations, and personalized horoscopes. Built with modern web technologies and optimized for mobile devices.

✨ Features

🌟 Core Features

• Birth Chart Generation: Accurate natal chart calculations using professional astrology algorithms
• Interactive Chart Wheel: Touch-enabled visualization with zoom, rotation, and detailed information
• Multiple Chart Types: Natal, transit, composite, progressed, solar return, and lunar return charts
• Personalized Horoscopes: Daily, weekly, and monthly horoscopes based on your birth chart
• User Profiles: Manage multiple birth charts for family and friends
• Planetary Transits: Track current planetary movements and their impact on your life

🎨 User Experience

• Mobile-First Design: Optimized for smartphones and tablets
• Progressive Web App: Install on your device for native-like experience
• Dark Theme: Mystical dark theme optimized for astrology viewing
• Smooth Animations: Subtle animations enhance the cosmic experience
• Offline Support: Access saved charts and horoscopes without internet connection

🔧 Technical Features

• High Accuracy: Uses Flatlib library for precise astronomical calculations
• Multiple House Systems: Placidus, Koch, Regiomontanus, Campanus, Equal, Whole Sign
• Comprehensive Aspects: All major aspect types with customizable orbs
• Location Services: Automatic timezone detection and location search
• Cross-Platform: Works on iOS, Android, and web browsers

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Python 3.9+ and pip
• Docker and Docker Compose (recommended)

Installation

1. Clone the repository

   git clone https://github.com/CityscapeAtSunset/astrology-app.git
   cd astrology-app

2. Set up environment

   cp .env.example .env
   # Edit .env with your configuration

3. Start with Docker Compose (recommended)

   docker-compose up -d

4. Manual setup (alternative)

   # Install frontend dependencies
   npm install
   
   # Install backend dependencies
   cd api-server
   pip install -r requirements.txt
   cd ..
   
   # Start both services
   npm run dev

5. Open the application

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

📱 Mobile App

Android

1. Build the app

   npm run build
   npx cap sync android

2. Open Android Studio

   npx cap open android

3. Run on device or emulator

   npx cap run android

iOS

1. Build the app

   npm run build
   npx cap sync ios

2. Open Xcode

   npx cap open ios

3. Run on device or simulator

🏗️ Project Structure

astrology-app/
├── public/                     # Static assets and PWA files
├── src/
│   ├── components/            # Reusable React components
│   │   ├── common/           # Generic UI components
│   │   ├── chart/            # Chart-specific components
│   │   └── layout/           # Layout components
│   ├── pages/                # Page components
│   │   ├── Home/             # Home page
│   │   ├── Chart/            # Birth chart page
│   │   ├── Horoscope/        # Horoscope page
│   │   ├── Profile/          # User profiles
│   │   └── Settings/         # App settings
│   ├── services/             # Business logic and API calls
│   ├── store/                # Redux state management
│   ├── types/                # TypeScript type definitions
│   ├── utils/                # Utility functions
│   └── styles/               # CSS and styling
├── api-server/               # FastAPI backend
│   ├── models/               # Data models
│   ├── routes/               # API endpoints
│   ├── services/             # Business logic
│   └── tests/                # Backend tests
├── docs/                     # Documentation
├── android/                  # Android platform files
└── tests/                    # Test files

🛠️ Technology Stack

Frontend

• React 18+ - Modern UI library with hooks and concurrent features
• TypeScript - Type-safe JavaScript development
• Ionic Framework - Mobile-first UI components and native capabilities
• Capacitor - Native app deployment for iOS and Android
• Redux Toolkit - State management with Redux
• RTK Query - Data fetching and caching
• Framer Motion - Animation library
• Chart.js - Chart rendering and visualization
• Vite - Fast build tool and development server

Backend

• FastAPI - Modern Python web framework
• Pydantic - Data validation and serialization
• Flatlib - Astrology calculation library
• Uvicorn - ASGI server
• PostgreSQL - Database (production)
• Redis - Caching (production)

Development Tools

• ESLint - Code linting
• Prettier - Code formatting
• Vitest - Testing framework
• Testing Library - Component testing
• Docker - Containerization

📚 Documentation

• User Guide - Complete user documentation
• Developer Guide - Technical documentation for developers
• API Documentation - Backend API reference
• Deployment Guide - Deployment instructions

🌐 API Documentation

The Astrology App provides a comprehensive RESTful API for astrology calculations:

Main Endpoints

• POST /api/v1/astrology/calculate - Calculate birth charts
• POST /api/v1/astrology/planetary-positions - Get planetary positions
• POST /api/v1/astrology/transits - Calculate transits
• POST /api/v1/astrology/zodiac-sign - Get zodiac sign information
• GET /api/v1/location/search - Search for locations

Interactive Documentation

Visit http://localhost:8000/docs for interactive API documentation.

🧪 Testing

Frontend Tests

# Run all tests
npm run test

# Run tests with UI
npm run test:ui

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Backend Tests

cd api-server

# Run all tests
python -m pytest

# Run tests with coverage
python -m pytest --cov=.

# Run specific test file
python -m pytest tests/test_astrology_service.py

End-to-End Tests

# Run E2E tests
npm run test:e2e

# Run E2E tests in headed mode
npm run test:e2e:headed

🔧 Development

Scripts

# Development
npm run dev              # Start development server
npm run preview          # Preview production build

# Building
npm run build            # Build for production
npm run build:analyze    # Analyze bundle size

# Code Quality
npm run lint             # Run ESLint
npm run format           # Format code with Prettier
npm run type-check       # TypeScript type checking

# Testing
npm run test             # Run unit tests
npm run test:ui          # Run tests with UI
npm run test:e2e         # Run E2E tests

# Mobile
npm run cap:sync         # Sync with Capacitor
npm run cap:open:android # Open Android project
npm run cap:open:ios     # Open iOS project

Environment Variables

Create a .env file based on .env.example:

# API Configuration
VITE_API_BASE_URL=http://localhost:8000/api/v1
VITE_API_TIMEOUT=10000

# App Configuration
VITE_APP_NAME=Astrology App
VITE_APP_VERSION=1.0.0

# Feature Flags
VITE_ENABLE_ANALYTICS=false
VITE_ENABLE_CRASH_REPORTING=true

Code Style

The project follows strict code style guidelines:

• ESLint for code linting
• Prettier for code formatting
• TypeScript for type safety
• Conventional Commits for commit messages

# Lint and format code
npm run lint:fix
npm run format

# Check commit message
npm run commitlint

📦 Deployment

Frontend Deployment

The frontend can be deployed to various platforms:

Netlify

# Install Netlify CLI
npm install -g netlify-cli

# Deploy
netlify deploy --prod --dir=dist

Vercel

# Install Vercel CLI
npm install -g vercel

# Deploy
vercel --prod

AWS S3

# Deploy to S3
aws s3 sync dist/ s3://your-bucket-name --delete

Backend Deployment

Heroku

# Deploy to Heroku
git subtree push --prefix api-server heroku main

Docker

# Build and run with Docker
docker build -t astrology-api ./api-server
docker run -p 8000:8000 astrology-api

Production Environment

For production deployment, see the Deployment Guide.

🤝 Contributing

We welcome contributions to the Astrology App! Please follow these steps:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
   • Follow the code style guidelines
   • Add tests for new features
   • Update documentation
4. Commit your changes

   git commit -m "feat: add amazing feature"

5. Push to the branch

   git push origin feature/amazing-feature

6. Create a Pull Request

Contribution Guidelines

• Follow the Conventional Commits specification
• Write descriptive commit messages
• Add tests for new features
• Update documentation
• Ensure all tests pass

Code of Conduct

Please be respectful and inclusive. Read our Code of Conduct for details.

📝 Changelog

Version 1.0.0 (2023-10-16)

Features

• ✨ Birth chart calculation with multiple house systems
• ✨ Interactive chart wheel with touch gestures
• ✨ Personalized horoscopes based on birth data
• ✨ User profile management
• ✨ Planetary transit calculations
• ✨ Location search and timezone detection
• ✨ Mobile app deployment for iOS and Android
• ✨ Progressive Web App capabilities
• ✨ Dark theme with mystical design
• ✨ Offline support for saved charts

Technical Features

• 🛠️ React 18 with TypeScript
• 🛠️ Ionic Framework for mobile UI
• 🛠️ Redux Toolkit for state management
• 🛠️ FastAPI backend with Flatlib
• 🛠️ Comprehensive test suite
• 🛠️ Docker containerization
• 🛠️ CI/CD pipeline

Documentation

• 📚 Complete user guide
• 📚 Developer documentation
• 📚 API documentation
• 📚 Deployment guide

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Flatlib - Astrology calculation library
• Ionic Framework - Mobile UI components
• Redux Toolkit - State management
• Framer Motion - Animations
• FastAPI - Backend framework

📞 Support

• Documentation: https://docs.astrologyapp.com
• Issues: GitHub Issues
• Email: support@astrologyapp.com
• Discord: Join our community

🌟 Star History

---

Made with ❤️ and cosmic energy

✨ Explore the cosmos within you ✨