adding current revision information

2026-01-02 08:29:16 -05:00
parent 789465483c
commit 920947e556
64 changed files with 5963 additions and 18 deletions
@@ -0,0 +1,140 @@
+# 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:
+    ```bash
+    cd backend
+    ```
+2.  Create and activate a virtual environment:
+    ```bash
+    python3 -m venv .venv
+    source .venv/bin/activate
+    ```
+3.  Install the dependencies:
+    ```bash
+    pip install -r requirements.txt
+    ```
+4.  Run the database migrations:
+    ```bash
+    alembic upgrade head
+    ```
+5.  Create the initial data (signs and admin user):
+    ```bash
+    python initial_data.py
+    python create_admin.py
+    ```
+6.  Run the backend server:
+    ```bash
+    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:
+    ```bash
+    cd frontend/horoscope-app
+    ```
+2.  Install the dependencies:
+    ```bash
+    npm install
+    ```
+3.  Run the frontend server:
+    ```bash
+    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.