From 90c22138531bcdb888dba725f13bf8ada2c4e49b Mon Sep 17 00:00:00 2001 From: Automated Action Date: Tue, 27 May 2025 20:42:52 +0000 Subject: [PATCH] Update README with comprehensive project documentation - Add detailed project overview and features - Include installation and setup instructions - Document API endpoints and structure - Add development guidelines and information - Improve project documentation for users and contributors --- README.md | 212 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 210 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e8acfba..6a01334 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,211 @@ -# FastAPI Application +# Weather Dashboard API -This is a FastAPI application bootstrapped by BackendIM, the AI-powered backend generation platform. +A powerful API for retrieving weather data, forecasts, and managing location bookmarks, built with FastAPI and SQLite. + +## Features + +- **User Authentication**: Secure JWT-based authentication +- **Current Weather Data**: Get real-time weather information for any location +- **Weather Forecasts**: Access 5-day weather forecasts +- **Location Bookmarking**: Save and manage your favorite locations +- **Default Location**: Set a default location for quick weather checks +- **Caching**: Efficient caching to minimize external API calls +- **OpenAPI Documentation**: Auto-generated, interactive API documentation + +## Tech Stack + +- **Framework**: FastAPI +- **Database**: SQLite with SQLAlchemy ORM +- **Migrations**: Alembic +- **Authentication**: JWT with OAuth2 +- **Password Hashing**: Bcrypt +- **HTTP Client**: HTTPX +- **External API**: OpenWeatherMap API +- **Documentation**: Swagger UI / ReDoc + +## Prerequisites + +- Python 3.8+ +- OpenWeatherMap API key (free tier available) + +## Environment Variables + +Create a `.env` file in the root directory with the following variables: + +``` +OPENWEATHER_API_KEY=your_api_key_here +SECRET_KEY=your_secret_key_here +``` + +## Installation + +1. Clone the repository: + +```bash +git clone https://github.com/yourusername/weather-dashboard-api.git +cd weather-dashboard-api +``` + +2. Install dependencies: + +```bash +pip install -r requirements.txt +``` + +3. Set up the database: + +```bash +alembic upgrade head +``` + +## Running the Application + +Start the development server: + +```bash +uvicorn main:app --reload +``` + +The API will be available at http://localhost:8000 + +## API Documentation + +Interactive API documentation is available at: + +- Swagger UI: http://localhost:8000/docs +- ReDoc: http://localhost:8000/redoc + +## API Endpoints + +### Authentication + +- `POST /api/v1/users/register` - Register a new user +- `POST /api/v1/users/login` - Login and get access token +- `GET /api/v1/users/me` - Get current user information + +### Weather Data + +- `GET /api/v1/weather/current` - Get current weather for specific coordinates +- `GET /api/v1/weather/current/default` - Get current weather for default location +- `GET /api/v1/weather/forecast` - Get 5-day forecast for specific coordinates +- `GET /api/v1/weather/forecast/default` - Get 5-day forecast for default location + +### Location Management + +- `GET /api/v1/locations` - Get all saved locations +- `GET /api/v1/locations/default` - Get default location +- `POST /api/v1/locations` - Create a new location +- `GET /api/v1/locations/{location_id}` - Get a specific location +- `PUT /api/v1/locations/{location_id}` - Update a specific location +- `DELETE /api/v1/locations/{location_id}` - Delete a specific location + +### Health Check + +- `GET /health` - Check API health status + +## Database Models + +### User + +- ID +- Email (unique) +- Username (unique) +- Hashed Password +- Is Active +- Is Superuser +- Created At +- Updated At +- Relationships: Locations + +### Location + +- ID +- Name +- Latitude +- Longitude +- Country (optional) +- Is Default +- Created At +- Updated At +- User ID (foreign key) +- Relationships: User + +## Project Structure + +``` +weather-dashboard-api/ +├── alembic.ini # Alembic configuration +├── main.py # FastAPI application entry point +├── requirements.txt # Python dependencies +├── app/ # Application package +│ ├── api/ # API endpoints +│ │ ├── deps.py # API dependencies +│ │ └── v1/ # API version 1 +│ │ ├── endpoints/ # API route handlers +│ │ └── router.py # API router +│ ├── core/ # Core functionality +│ │ ├── config.py # App configuration +│ │ └── security.py # Security utilities +│ ├── crud/ # CRUD operations +│ ├── db/ # Database setup +│ │ └── session.py # DB session +│ ├── models/ # SQLAlchemy models +│ ├── schemas/ # Pydantic schemas +│ └── services/ # Business logic services +│ ├── cache_service.py # Caching service +│ └── weather_service.py # Weather API client +└── migrations/ # Alembic migrations + ├── env.py # Migration environment + ├── script.py.mako # Migration template + └── versions/ # Migration scripts +``` + +## Error Handling + +The API includes comprehensive error handling: + +- Invalid input validation +- Authentication and authorization errors +- Resource not found errors +- External API communication errors +- Rate limiting and caching errors + +## Caching Strategy + +The API implements a simple in-memory caching strategy to minimize calls to the OpenWeatherMap API: + +- Cache duration is configurable (default: 5 minutes) +- Separate cache keys for current weather and forecasts +- Automatic cache invalidation on expiration + +## Development + +To contribute to this project: + +1. Create a feature branch: +```bash +git checkout -b feature/your-feature-name +``` + +2. Make your changes and run tests: +```bash +pytest +``` + +3. Run code linting: +```bash +ruff check --fix +``` + +4. Submit a pull request + +## License + +This project is licensed under the MIT License - see the LICENSE file for details. + +## Acknowledgements + +- [FastAPI](https://fastapi.tiangolo.com/) +- [SQLAlchemy](https://www.sqlalchemy.org/) +- [Alembic](https://alembic.sqlalchemy.org/) +- [OpenWeatherMap API](https://openweathermap.org/api) \ No newline at end of file