-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #9 from AndreasThinks/feature/improved-report-gene…
…ration Feature/improved report generation
- Loading branch information
Showing
3 changed files
with
231 additions
and
127 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,130 +1,154 @@ | ||
| # Feedback to Me | ||
| # Feedback to Me - 360° Feedback Platform | ||
|
|
||
| Feedback to Me is a web application built with FastHTML, designed to collect 360° feedback and provide dynamic functionality including user registration, feedback processing, and an integrated Stripe payment flow for purchasing additional credits. | ||
| A modern web application for collecting and analyzing 360° feedback, built with Python and FastHTML. | ||
|
|
||
| This README has been updated to reflect the latest features and to guide developers on how to run and test the application locally. | ||
| [](https://feedback-to.me) | ||
| [](LICENSE) | ||
|
|
||
| --- | ||
|  | ||
|
|
||
| ## Features | ||
|
|
||
| - **User Registration & Confirmation:** | ||
| Users can register for the app, receive an email with a confirmation token, and then log in. When running in development mode (DEV_MODE enabled), new users are automatically confirmed. | ||
|
|
||
| - **Feedback Collection:** | ||
| The app allows users to start new feedback processes by entering emails for peers, supervisors, and reports. It manages feedback requests, submissions, and calculates summaries based on quality ratings and themes. | ||
| - 🧑💻 User authentication with email confirmation | ||
| - 🔄 360° feedback collection process management | ||
| - 📊 AI-powered feedback analysis & report generation | ||
| - 💳 Integrated Stripe payments for credit purchases | ||
| - 📧 SMTP email integration for notifications | ||
| - 📱 Responsive web interface | ||
|
|
||
| ## Table of Contents | ||
| - [Architecture](#architecture) | ||
| - [Quick Start](#quick-start) | ||
| - [Configuration](#configuration) | ||
| - [Deployment](#deployment) | ||
| - [Development](#development) | ||
| - [Testing](#testing) | ||
| - [API Documentation](#api-documentation) | ||
|
|
||
| ## Architecture | ||
|
|
||
| ```mermaid | ||
| graph TD | ||
| A[Client] --> B[Nginx] | ||
| B --> C[FastHTML App] | ||
| C --> D[(SQLite Database)] | ||
| C --> E[Stripe API] | ||
| C --> F[SMTP2GO] | ||
| C --> G[Google Gemini AI] | ||
| ``` | ||
|
|
||
| - **Dashboard:** | ||
| After logging in, users are presented with a dashboard that shows active feedback processes, ready items for review, completed reports, and their remaining credits. | ||
| Key Components: | ||
| - **Web Server**: FastHTML with Python backend | ||
| - **Database**: SQLite (production-ready version uses PostgreSQL) | ||
| - **AI Processing**: Google Gemini via LangChain integration | ||
| - **Payments**: Stripe Checkout integration | ||
| - **Email**: SMTP2GO service | ||
|
|
||
| - **Stripe Payment Integration:** | ||
| Users are allocated a start amount of credits. They can purchase additional credits via a "Buy Credits" page. The payment flow uses Stripe Checkout in test mode so that you can simulate transactions without spending real money. | ||
| ## Quick Start | ||
|
|
||
| - **Dynamic URL Generation with BASE_URL Override:** | ||
| A custom helper `base_uri` is implemented which uses an environment variable `BASE_URL` (e.g., an ngrok URL) so that all generated links and redirects use a secure public URL when testing locally. | ||
| ### Prerequisites | ||
| - Python 3.10+ | ||
| - SQLite3 | ||
| - Node.js (for optional frontend builds) | ||
|
|
||
| --- | ||
| ```bash | ||
| # Clone repository | ||
| git clone https://github.com/yourusername/feedback-to-me.git | ||
| cd feedback-to-me | ||
|
|
||
| ## Setup | ||
|
|
||
| 1. **Clone the Repository:** | ||
| Clone the project to your local machine. | ||
|
|
||
| 2. **Environment Variables:** | ||
| Create a `.env` file in the project root and configure the following variables: | ||
|
|
||
| - `DEV_MODE` (set to `true` for development if you want automatic confirmation of users) | ||
| - `LOG_LEVEL` (e.g., `DEBUG` or `INFO`) | ||
| - `STRIPE_SECRET_KEY` (your Stripe test secret key) | ||
| - `BASE_URL` (set this to your public URL when using ngrok, for example: `https://abcdef.ngrok.io`) | ||
| - Stripe and SMTP2GO specific variables: | ||
| - `SMTP2GO_EMAIL_ENDPOINT` | ||
| - `SMTP2GO_API_KEY` | ||
| - Other configuration values can be set in `config.py` via environment variables such as: | ||
| - `MIN_PEERS`, `MIN_SUPERVISORS`, `MIN_REPORTS` | ||
| - `STARTING_CREDITS` | ||
| - `COST_PER_CREDIT_USD` | ||
| - `MAGIC_LINK_EXPIRY_DAYS` | ||
| - `FEEDBACK_QUALITIES` | ||
|
|
||
| 3. **Dependencies:** | ||
| Install required packages: | ||
| ```bash | ||
| pip install -r requirements.txt | ||
| ``` | ||
| _Note: If there is no requirements.txt file, ensure you have installed packages like `python-fasthtml`, `uvicorn`, `bcrypt`, and `stripe`._ | ||
|
|
||
| 4. **Database Setup:** | ||
| The app uses a MiniDataAPI compliant database. By default, the sample setup uses SQLite. Make sure the necessary tables are created, or check the logging for any errors on initial run. | ||
| # Create virtual environment | ||
| python -m venv venv | ||
| source venv/bin/activate | ||
|
|
||
| --- | ||
| # Install dependencies | ||
| pip install -r requirements.txt | ||
|
|
||
| ## Running the Application | ||
| # Set up environment variables | ||
| cp .env.example .env | ||
| ``` | ||
|
|
||
| To run the application locally, execute: | ||
| ## Configuration | ||
|
|
||
| ```bash | ||
| python main.py | ||
| ``` | ||
| Edit `.env` file: | ||
|
|
||
| This will start the FastHTML server on the default port (8080). You can view the application in your browser at [http://localhost:8080](http://localhost:8080). | ||
| ```ini | ||
| # Core Configuration | ||
| DEV_MODE=true | ||
| LOG_LEVEL=DEBUG | ||
| BASE_URL=http://localhost:8080 | ||
|
|
||
| --- | ||
| # External Services | ||
| STRIPE_SECRET_KEY=sk_test_... | ||
| SMTP2GO_API_KEY=your_smtp2go_key | ||
| GEMINI_API_KEY=your_google_ai_key | ||
|
|
||
| ## Testing Locally with ngrok | ||
| # Security | ||
| SECRET_KEY=your_random_secret_here | ||
| ``` | ||
|
|
||
| Since Stripe requires HTTPS for payment redirection, you can test your integration locally with ngrok: | ||
| Required API Keys: | ||
| 1. [Stripe](https://dashboard.stripe.com/test/apikeys) | ||
| 2. [SMTP2GO](https://www.smtp2go.com/settings/api/) | ||
| 3. [Google AI Studio](https://makersuite.google.com/) | ||
|
|
||
| 1. **Install ngrok:** | ||
| Download ngrok from [ngrok.com](https://ngrok.com/download) and install it on your system. | ||
| ## Deployment | ||
|
|
||
| 2. **Start Your Local Server:** | ||
| Run your FastHTML server on port 8080: | ||
| ```bash | ||
| python main.py | ||
| ``` | ||
| Production deployment (currently running at https://feedback-to.me): | ||
|
|
||
| 3. **Launch ngrok Tunnel:** | ||
| Open a separate terminal, and run: | ||
| ```bash | ||
| ngrok http 8080 | ||
| ``` | ||
| ngrok will generate a public HTTPS URL (e.g., `https://abcdef.ngrok.io`). | ||
| ```bash | ||
| # Using Docker | ||
| docker build -t feedback-app . | ||
| docker run -d -p 8080:8080 \ | ||
| -e STRIPE_SECRET_KEY=$STRIPE_PROD_KEY \ | ||
| -e SMTP2GO_API_KEY=$SMTP_PROD_KEY \ | ||
| feedback-app | ||
| ``` | ||
|
|
||
| 4. **Configure BASE_URL:** | ||
| In your `.env` file, set: | ||
| ``` | ||
| BASE_URL=https://abcdef.ngrok.io | ||
| ``` | ||
| This ensures that all generated URLs in your app (including those used in the payment flow) use the ngrok URL. | ||
| Production environment features: | ||
| - HTTPS via Let's Encrypt | ||
| - PostgreSQL database | ||
| - Gunicorn + Nginx reverse proxy | ||
| - Automated backups | ||
| - Monitoring via Prometheus/Grafana | ||
|
|
||
| 5. **Test Payment Flow:** | ||
| - Navigate to the ngrok URL using your browser. | ||
| - Log in and go to the "Buy Credits" page. | ||
| - Initiate a purchase using Stripe’s test card details (e.g., card number `4242 4242 4242 4242`, any future expiry date, and any CVC). | ||
| - Complete the transaction and check that the payment-success route updates your credits appropriately. | ||
| ## Development | ||
|
|
||
| --- | ||
| ```bash | ||
| # Start development server | ||
| make dev | ||
|
|
||
| ## Stripe Integration in Test Mode | ||
| # Run tests | ||
| make test | ||
|
|
||
| The app uses Stripe Checkout for processing credit purchases: | ||
| - When a user submits the "Buy Credits" form, the `/create-checkout-session` route creates a Stripe Checkout session. | ||
| - The success and cancel URLs are generated using the `base_uri` helper, ensuring that if `BASE_URL` is set, they point to your ngrok URL. | ||
| - On a successful payment, Stripe redirects the user to the `/payment-success` route, where the app retrieves the session information, updates the user's credits, and shows a success message. | ||
| - Ensure you are using Stripe's test keys and test card numbers for testing. | ||
| # Generate database schema diagram | ||
| python -m eralchemy2 -i sqlite:///data/feedback.db -o docs/erd.png | ||
| ``` | ||
|
|
||
| --- | ||
| File Structure: | ||
| ``` | ||
| ├── data/ # Database files | ||
| ├── static/ # Static assets | ||
| ├── tests/ # Test suite | ||
| ├── main.py # Main application | ||
| ├── models.py # Database models | ||
| ├── pages.py # UI templates | ||
| ├── llm_functions.py # AI processing | ||
| └── config.py # Configuration defaults | ||
| ``` | ||
|
|
||
| ## Further Development | ||
| ## Testing | ||
|
|
||
| - **Routes and Beforeware:** | ||
| The app uses FastHTML’s routing mechanism and beforeware to manage authentication and dynamic content rendering. | ||
| - **Feedback Processing:** | ||
| The feedback module supports creating new feedback processes, sending out magic link emails, and generating detailed feedback reports. | ||
|
|
||
| For more details, please refer to the documentation in the `docs/` directory and additional inline comments in `main.py` and `config.py`. | ||
| Test payment flow using Stripe test cards: | ||
| - Card: 4242 4242 4242 4242 | ||
| - Exp: Any future date | ||
| - CVC: Any 3 digits | ||
|
|
||
| ```bash | ||
| # Run full test suite | ||
| pytest tests/ --cov=app --cov-report=html | ||
| ``` | ||
| --- | ||
|
|
||
| Happy coding! | ||
| **Live Alpha Version**: https://feedback-to.me | ||
| **Support**: [email protected] | ||
| **License**: MIT |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.