personal_development/horoscope/README.md

Horoscope Web Application

Project Overview

This project is a web application that provides daily, weekly, monthly, and yearly horoscopes for the 12 astrological signs. The horoscopes are generated using the Google Gemini API.

The application consists of a Python backend built with FastAPI and a React frontend built with Vite and Material UI.

Project Structure

horoscope/
├── backend/
│   ├── alembic/
│   ├── .venv/
│   ├── alembic.ini
│   ├── config.py
│   ├── create_admin.py
│   ├── database.py
│   ├── horoscope.py
│   ├── initial_data.py
│   ├── main.py
│   ├── models.py
│   ├── requirements.txt
│   └── schemas.py
├── frontend/
│   └── horoscope-app/
│       ├── public/
│       ├── src/
│       ├── index.html
│       ├── package.json
│       └── vite.config.ts
├── Objectives.md
└── README.md

Getting Started

Prerequisites

• Python 3.10 or higher
• Node.js and npm

Backend Setup

1. Navigate to the backend directory:

   cd backend
   

2. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install the dependencies:

   pip install -r requirements.txt
   

4. Run the database migrations:

   alembic upgrade head
   

5. Create the initial data (signs and admin user):

   python initial_data.py
   python create_admin.py
   

6. Run the backend server:

   uvicorn main:app --reload --host 0.0.0.0
   

   The backend will be available at http://localhost:8000.

Frontend Setup

1. Navigate to the frontend/horoscope-app directory:

   cd frontend/horoscope-app
   

2. Install the dependencies:

   npm install
   

3. Run the frontend server:

   npm run dev
   

   The frontend will be available at http://localhost:5173.

Backend

Technologies Used

• Python 3
• FastAPI
• SQLAlchemy with Alembic
• SQLite
• Google Gemini API

API Endpoints

• POST /token: Login to get a JWT token.
• GET /users/me: Get the current user's information.
• GET /signs: Get a list of all astrological signs.
• GET /horoscope/{sign}/{timeline}: Get a horoscope for a specific sign and timeline.
• POST /horoscope/{sign}/{timeline}: Create a new horoscope for a specific sign and timeline (admin only).

Database Schema

The database schema is defined in backend/models.py and consists of the following tables:

• users: Stores user information.
• signs: Stores the 12 astrological signs.
• user_signs: A many-to-many table that links users to their signs.
• horoscopes: Stores the generated horoscopes.

Frontend

Technologies Used

• React with Vite
• TypeScript
• Material UI
• Axios

Component Structure

• App.tsx: The main component that sets up the routing.
• components/AppBar.tsx: The top application bar.
• components/Login.tsx: The login form.
• components/Home.tsx: The home page that displays the horoscopes.
• services/api.ts: The Axios instance for making API calls.

Next Steps

• Implement the OIDC SSO with Keycloak.
• Allow users to create accounts and select their signs.
• Implement the export to PDF, HTML, and Word feature.
• Add the alchemical "mascot" bonus feature.
• Write more tests for the backend and frontend.
• Improve the UI/UX of the application.