{"id":48552840,"url":"https://github.com/umbertocicciaa/unical-dimes-professors","last_synced_at":"2026-04-08T09:03:22.671Z","repository":{"id":322107844,"uuid":"1087873354","full_name":"umbertocicciaa/unical-dimes-professors","owner":"umbertocicciaa","description":"Review your teachers","archived":false,"fork":false,"pushed_at":"2026-02-01T22:03:58.000Z","size":286,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-02T08:03:41.835Z","etag":null,"topics":["dimes","fastapi","react","university"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/umbertocicciaa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-01T20:23:27.000Z","updated_at":"2026-02-01T22:04:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/umbertocicciaa/unical-dimes-professors","commit_stats":null,"previous_names":["umbertocicciaa/unical-dimes-professors"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/umbertocicciaa/unical-dimes-professors","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbertocicciaa%2Funical-dimes-professors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbertocicciaa%2Funical-dimes-professors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbertocicciaa%2Funical-dimes-professors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbertocicciaa%2Funical-dimes-professors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/umbertocicciaa","download_url":"https://codeload.github.com/umbertocicciaa/unical-dimes-professors/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbertocicciaa%2Funical-dimes-professors/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31547848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dimes","fastapi","react","university"],"created_at":"2026-04-08T09:03:22.539Z","updated_at":"2026-04-08T09:03:22.660Z","avatar_url":"https://github.com/umbertocicciaa.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UNICAL DIMES Professors - Teacher Review Platform\n\nA modern full-stack web application for anonymous teacher and course reviews. Built with React, TypeScript, Python FastAPI, and PostgreSQL.\n\n## Features\n\n- 🌟 **Star Rating System**: 1-5 star ratings based on average votes\n- 🔐 **Secure Authentication**: Email + password login with Argon2 hashing and JWT access tokens\n- 🎓 **Teacher \u0026 Course Management**: Browse teachers and their courses\n- 🛠 **Admin Dashboard**: Role-gated UI for managing teachers, courses, reviews, and user roles\n- 💬 **Mandatory Descriptions**: All reviews require detailed descriptions (minimum 10 characters)\n- 📊 **Average Ratings**: Automatic calculation of average ratings\n- 🐳 **Docker Support**: Complete Docker setup for local development\n\n## Tech Stack\n\n### Frontend\n\n- React 18 with TypeScript\n- React Router for navigation\n- Axios for API communication\n- Modern CSS with responsive design\n\n### Backend\n\n- Python 3.11\n- FastAPI (modern async API framework)\n- SQLAlchemy (ORM)\n- PostgreSQL database\n- Pydantic for data validation\n\n### Infrastructure\n\n- Docker \u0026 Docker Compose\n- PostgreSQL 15\n\n## Project Structure\n\n```plain txt\nunical-dimes-professors/\n├── frontend/               # React TypeScript frontend\n│   ├── src/\n│   │   ├── api/           # API client\n│   │   ├── components/    # React components\n│   │   └── App.tsx        # Main app component\n│   ├── Dockerfile\n│   └── package.json\n├── backend/               # Python FastAPI backend\n│   ├── app/\n│   │   ├── models.py     # Database models\n│   │   ├── schemas.py    # Pydantic schemas\n│   │   ├── database.py   # Database configuration\n│   │   └── main.py       # FastAPI app\n│   ├── Dockerfile\n│   └── requirements.txt\n└── docker-compose.yml     # Docker orchestration\n```\n\n## Getting Started\n\n### Prerequisites\n\n- Docker Desktop (or Docker + Docker Compose)\n- Git\n\n### Installation \u0026 Running\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/umbertocicciaa/unical-dimes-professors.git\n   cd unical-dimes-professors\n   ```\n\n2. **Start the application with Docker Compose**\n\n   ```bash\n   docker-compose up --build\n   ```\n\n   This will start:\n   - PostgreSQL database on port 5432\n   - FastAPI backend on port 8000\n   - React frontend on port 3000\n\n3. **Access the application**\n   - Frontend: \u003chttp://localhost:3000\u003e\n   - Backend API: \u003chttp://localhost:8000\u003e\n   - API Documentation: \u003chttp://localhost:8000/docs\u003e\n\n### Local Development (without Docker)\n\n#### Backend Setup\n\n1. Create a virtual environment:\n\n   ```bash\n   cd backend\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n2. Install dependencies:\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. Set up environment variables:\n\n   ```bash\n   cp .env.example .env\n   # Edit .env with your database credentials and security secrets:\n   # AUTH_SECRET_KEY, AUTH_REFRESH_SECRET, ACCESS_TOKEN_EXPIRE_MINUTES, REFRESH_TOKEN_EXPIRE_DAYS\n   ```\n\n4. Start PostgreSQL (using Docker):\n\n   ```bash\n   docker run -d \\\n     --name professors-db \\\n     -e POSTGRES_USER=postgres \\\n     -e POSTGRES_PASSWORD=postgres \\\n     -e POSTGRES_DB=professors_db \\\n     -p 5432:5432 \\\n     postgres:15\n   ```\n\n5. Apply database migrations and seed roles/users:\n\n   ```bash\n   alembic upgrade head\n   python seed_data.py  # optional, creates demo data and a default admin user\n   ```\n\n6. Run the backend:\n\n   ```bash\n   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n   ```\n\n#### Frontend Setup\n\n1. Install dependencies:\n\n   ```bash\n   cd frontend\n   npm install\n   ```\n\n2. Start the development server:\n\n   ```bash\n   npm start\n   ```\n\n## API Endpoints\n\n### Authentication\n\n- `POST /auth/register` — Self-service registration (assigns the `viewer` role)\n- `POST /auth/login` — Exchange credentials for access and refresh tokens\n- `POST /auth/refresh` — Rotate refresh token and issue a new access token\n- `POST /auth/logout` — Revoke the active refresh token\n- `GET /auth/me` — Return the authenticated user profile and roles\n\n\u003e **Default roles**\n\u003e\n\u003e - `admin`: full CRUD and user management  \n\u003e - `editor`: manage teachers, courses, and reviews  \n\u003e - `viewer`: read catalog data and submit reviews  \n\u003e\n\u003e The seed script provisions an initial admin account using `DEFAULT_ADMIN_EMAIL` and `DEFAULT_ADMIN_PASSWORD`.\n\n### Teachers\n\n- `GET /api/teachers` — List all teachers with ratings\n- `GET /api/teachers/{id}` — Get teacher details\n- `POST /api/teachers` — Create a new teacher (**requires** `admin` or `editor`)\n- `PUT /api/teachers/{id}` — Update a teacher (**requires** `admin` or `editor`)\n- `DELETE /api/teachers/{id}` — Delete a teacher (**requires** `admin`)\n\n### Courses\n\n- `GET /api/courses` — List all courses\n- `GET /api/courses/{id}` — Get course details\n- `POST /api/courses` — Create a new course (**requires** `admin` or `editor`)\n- `PUT /api/courses/{id}` — Update a course (**requires** `admin` or `editor`)\n- `DELETE /api/courses/{id}` — Delete a course (**requires** `admin`)\n\n### Reviews\n\n- `GET /api/reviews` — List all reviews\n- `GET /api/teachers/{teacher_id}/reviews` — Get reviews for a specific teacher\n- `POST /api/reviews` — Create a new review (requires login; `viewer`+)\n- `PUT /api/reviews/{id}` — Update a review (**requires** `admin` or `editor`)\n- `DELETE /api/reviews/{id}` — Delete a review (**requires** `admin`)\n\n### Admin\n\n- `GET /admin/roles` — List configured roles (**requires** `admin`)\n- `GET /admin/users` — List users with role assignments (**requires** `admin`)\n- `PUT /admin/users/{id}` — Update user status and role memberships (**requires** `admin`)\n\n## Usage Guide\n\n### Adding a Teacher\n\n1. Use the API to add a teacher:\n\n   ```bash\n   curl -X POST http://localhost:8000/api/teachers \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"name\": \"Prof. John Doe\", \"department\": \"Computer Science\"}'\n   ```\n\n### Adding a Course\n\n1. Add a course for a teacher:\n\n   ```bash\n   curl -X POST http://localhost:8000/api/courses \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"name\": \"Data Structures\", \"teacher_id\": 1}'\n   ```\n\n### Submitting a Review\n\n1. Open the frontend at \u003chttp://localhost:3000\u003e\n2. Click on a teacher card\n3. Click \"Add Review\"\n4. Select a course, rate (1-5 stars), and write a description (min 10 characters)\n5. Submit the review\n\n### Admin Dashboard\n\n1. Sign in with an account that has the `admin` role (the seed script creates `DEFAULT_ADMIN_EMAIL` with full access).\n2. Navigate to \u003chttp://localhost:3000/admin\u003e.\n3. Use the tabbed interface to add/edit/delete teachers, courses, and reviews.\n4. Manage users by toggling roles and account status—changes are persisted via the `/admin` API.\n\n## Database Schema\n\n### Teachers\n\n- `id`: Primary key\n- `name`: Teacher name\n- `department`: Department name (optional)\n- `created_at`: Timestamp\n\n### Courses\n\n- `id`: Primary key\n- `name`: Course name\n- `teacher_id`: Foreign key to teachers\n- `created_at`: Timestamp\n\n### Reviews\n\n- `id`: Primary key\n- `teacher_id`: Foreign key to teachers\n- `course_id`: Foreign key to courses\n- `rating`: Integer (1-5)\n- `description`: Text (minimum 10 characters)\n- `created_at`: Timestamp\n\n## Development\n\n### Running Tests\n\nBackend:\n\n```bash\ncd backend\npytest\n```\n\nFrontend:\n\n```bash\ncd frontend\nnpm test\n```\n\n### Code Style\n\nBackend:\n\n```bash\ncd backend\nblack app/\nflake8 app/\n```\n\nFrontend:\n\n```bash\ncd frontend\nnpm run lint\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is open source and available under the MIT License.\n\n## Support\n\nFor issues, questions, or contributions, please open an issue on GitHub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumbertocicciaa%2Funical-dimes-professors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumbertocicciaa%2Funical-dimes-professors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumbertocicciaa%2Funical-dimes-professors/lists"}