From 7461b1348c28005ab575f15d4e74f5695c1dbace Mon Sep 17 00:00:00 2001 From: th0truth Date: Fri, 8 May 2026 11:26:02 +0300 Subject: [PATCH] update: README.md --- README.md | 194 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 162 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index f4fe923..49f7663 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,185 @@ # Unified API -**Unified API**, is a RESTful API that offers simplify tasks with course managment, assesment and related operations for educational institutions. It provides endpoints for handling users, groups, disciplines, courses, etc. +Unified API is an asynchronous FastAPI service for education management workflows. It provides versioned REST endpoints for authentication, user profiles, groups, students, teachers, schedules, lesson attachments, and assessment data. + +The service is designed around a MongoDB-backed domain model, Redis-backed caching and rate limiting, JWT authentication, Google OAuth, and containerized deployment with Docker Compose and Nginx. + +## Features + +- **FastAPI application** with automatic OpenAPI, Swagger UI, and ReDoc documentation. +- **Versioned REST API** mounted under `/api/v1`. +- **Authentication and authorization** with OAuth2 password login, Google OAuth, RS256 JWTs, token refresh, logout, and Redis-backed token revocation. +- **Role-aware rate limiting** using SlowAPI and Redis. +- **MongoDB integration** through PyMongo's asynchronous client. +- **Redis integration** for user-profile caching, token blacklist entries, and limiter storage. +- **Education domain endpoints** for users, groups, students, teachers, schedules, grades, assessments, and lesson files. +- **Cloudinary integration** for lesson attachment uploads. +- **Pydantic settings and schemas** for validation, serialization, and environment-based configuration. +- **Docker-first deployment** with an application container and Nginx reverse proxy. +- **Async test setup** using pytest, pytest-asyncio, HTTPX, and ASGITransport. + +## Tech Stack + +- Python 3.11+ +- FastAPI +- Pydantic v2 and pydantic-settings +- Uvicorn +- MongoDB Atlas-compatible connection string +- Redis +- PyJWT with RS256 signing +- Passlib with Argon2 password hashing +- Authlib for Google OAuth +- SlowAPI for rate limiting +- Cloudinary +- Docker and Docker Compose +- uv for dependency management + +## API Overview + +The application exposes OpenAPI metadata at: + +- `GET /api/openapi.json` + +Interactive documentation is available when the service is running: + +- Swagger UI: `http://localhost:10000/docs` +- ReDoc: `http://localhost:10000/redoc` + +Main API groups: + +| Area | Base path | Purpose | +| --- | --- | --- | +| Health | `/api/v1/health` | Service health check | +| Authentication | `/api/v1/auth` | Login, token refresh, logout, and Google OAuth | +| Current user | `/api/v1/user` | Current profile, initial data, email/password updates, recovery | +| Users | `/api/v1/users` | User lookup, updates, deletion, and role-based listing | +| Groups | `/api/v1/groups` | Group creation, lookup, listing, and deletion | +| Students | `/api/v1/students` | Student creation, group membership, disciplines, grades, and assessments | +| Teachers | `/api/v1/teachers` | Teacher creation and assigned groups/disciplines | +| Schedule | `/api/v1/schedule` | Lesson scheduling, lesson updates, deletion, and attachments | + +## Project Structure + +```text +. +├── src/app +│ ├── api # FastAPI routers and dependencies +│ ├── core # Configuration, database clients, middleware, security, schemas +│ ├── crud # MongoDB data-access helpers +│ └── main.py # FastAPI application factory and lifespan hooks +├── src/tests # Async route tests +├── nginx/default.conf # Nginx reverse proxy configuration +├── scripts # Build, run, and clean helper scripts +├── compose.yaml # Docker Compose services +├── Dockerfile # Application image +├── pyproject.toml # Python dependencies and project metadata +├── uv.lock # Locked dependency graph +└── pytest.ini # Test configuration +``` + +## Requirements + +- Python 3.11 or newer +- Docker and Docker Compose +- A MongoDB database +- A Redis instance +- Google OAuth credentials +- Cloudinary credentials +- uv, if running locally outside Docker + +## Configuration + +Create a local environment file from the example: + +```bash +cp .env.example .env +``` -## **Features** +Fill in all required values in `.env`. -- High-performace Python web framework for building APIs with automatic OpenAPI & Swagger & ReDoc docs. -- Fully async using async def path operation, enabling non-blocking oprations. -- Fast and robust data validation and serialization using Pydantic library. -- Secure authentification using OAuth2.0 standard with username / password and access token (JWT). -- NoSQL databases: - - Integrated with MongoDB using an async pymongo (related to 4.13 version) for efficient data access. - - Supports Redis caching using async aioredis. -- Seamless containerzation using Docker / Docker compose. -- Test suite using pytest framework. -- Environment configuration. +Important settings: +| Variable group | Description | +| --- | --- | +| `NAME`, `DESCRIPTION`, `SUMMARY`, `VERSION` | FastAPI metadata shown in generated docs | +| `FRONTEND_HOST`, `BACKEND_CORS_ORIGINS` | CORS and session-related origins | +| `MONGO_*` | MongoDB hostname, credentials, database name, and pool settings | +| `REDIS_*` | Redis host, port, credentials, database, cache, and limiter storage | +| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | Google OAuth client credentials | +| `SECRET_KEY` | Starlette session middleware secret | +| `RATE_LIMIT_*` | Request limits for admins, students, teachers, and anonymous users | +| `CLOUDINARY_*` | Cloudinary upload credentials | +| `JWT_ALGORITHM`, `JWT_EXPIRE_MINUTES` | JWT signing algorithm and token lifetime | -# **Installation** +`BACKEND_CORS_ORIGINS` accepts a comma-separated list, for example: -The current recommend way to install UnifiedAPI is from source. +```env +BACKEND_CORS_ORIGINS=http://localhost,http://localhost:10000,https://example.com +``` + +## Local Development -## From source +Install dependencies and create a virtual environment: ```bash -git clone https://github.com/UnifiedLS/api.git -cd api +bash scripts/build.sh ``` -## Requirements +Activate the environment: + +```bash +source .venv/bin/activate +``` + +Run the API locally: + +```bash +PYTHONPATH=src/app uv run uvicorn main:app --host 0.0.0.0 --port 10000 --reload +``` + +The API will be available at: + +```text +http://localhost:10000 +``` -- [Python +3.11](https://www.python.org/downloads/) -- [Docker](https://docs.docker.com/get-started/get-docker/) +## Docker Usage + +Build and start the application stack: + +```bash +bash scripts/run.sh +``` -# Configure +This runs: -You must rename `.env.example` to `.env `and fill in your required secrets and configuration values. +- the FastAPI application container +- the Nginx reverse proxy container -## **Usage** +Both services use host networking as configured in `compose.yaml`. -If you have installed `bash`. +To stop the stack: ```bash -bash scripts/build.sh +docker compose down +``` + +## Testing -bash scripts/run.sh +Run the test suite with: + +```bash +uv run pytest ``` -## **Docs** - - # Swagger UI: - - http://localhost:10000/docs +The pytest configuration sets `src/app` as the Python path and discovers tests under `src/tests`. + +## Runtime Behavior + +On startup, the FastAPI lifespan handler connects to Redis and MongoDB. On shutdown, both clients are closed cleanly. + +Authentication uses bearer tokens issued by `/api/v1/auth/login`. JWT IDs are tracked in Redis when tokens are refreshed or revoked so logged-out tokens cannot be reused. User profile data can also be cached in Redis to reduce MongoDB reads. + +## License - # ReDoc UI: - - http://localhost:10000/redoc +This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. \ No newline at end of file