{"id":50388325,"url":"https://github.com/rckbrcls/cefer","last_synced_at":"2026-05-30T16:30:41.621Z","repository":{"id":355493405,"uuid":"1134664482","full_name":"rckbrcls/cefer","owner":"rckbrcls","description":"Academic database app for managing sports facility reservations, activities, users, reports, and PostgreSQL rules.","archived":false,"fork":false,"pushed_at":"2026-05-04T01:34:36.000Z","size":11482,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T03:28:43.938Z","etag":null,"topics":["academic-project","database-course","docker-compose","flask","nextjs","postgresql","react","sports-facility","sql","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"nluizsoliveira/db_project","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rckbrcls.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":"docs/security.md","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":"2026-01-15T02:56:18.000Z","updated_at":"2026-05-04T01:34:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rckbrcls/cefer","commit_stats":null,"previous_names":["rckbrcls/db_project","rckbrcls/cefer"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rckbrcls/cefer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fcefer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fcefer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fcefer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fcefer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rckbrcls","download_url":"https://codeload.github.com/rckbrcls/cefer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fcefer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33700863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"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":["academic-project","database-course","docker-compose","flask","nextjs","postgresql","react","sports-facility","sql","typescript"],"created_at":"2026-05-30T16:30:40.700Z","updated_at":"2026-05-30T16:30:41.613Z","avatar_url":"https://github.com/rckbrcls.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CEFER Management\n\n\u003e Status: archived academic coursework reference.\n\nCEFER Management is a full-stack academic system for managing sports-facility reservations, activities, equipment, users, external invitations, and reporting workflows for the CEFER context at USP. It was built for the SCC0641 database laboratory coursework and is preserved as a database-first portfolio and study project, not as an actively maintained production product.\n\nThe project combines a PostgreSQL relational model, a Flask API, a Next.js client, SQL functions/views/triggers, synthetic data generators, and Docker Compose orchestration.\n\n## What This Project Solves\n\nThe system models a sports center where different user profiles need different workflows:\n\n- Internal USP users can view available activities, enroll in activities, reserve installations, reserve equipment, and invite external guests.\n- Staff users can manage activities, participants, equipment reservations, and installation reservations.\n- Administrators can manage users, installations, equipment, events, extension groups, activities, reservations, and registration requests.\n- External users can authenticate through invitation tokens and accept or reject participation invitations.\n- Reports and database views expose analytical summaries for reservations, activities, equipment, installations, and participation.\n\n## Main Features\n\n- Role-based web UI for administrators, staff, internal users, and external invitees.\n- Flask API grouped by domain under `server/app/routes/`.\n- PostgreSQL schema, indexes, views, PL/pgSQL functions, and triggers under `server/sql/`.\n- Synthetic data generation under `server/data_generators/`.\n- Session-based authentication for internal users.\n- Token-based external invite flow.\n- Docker Compose setup for PostgreSQL, Flask, and Next.js.\n- Academic report artifacts preserved under `relatorio.md` and `docs/entrega_final/`.\n\n## Technology Stack\n\n| Area | Technology |\n| --- | --- |\n| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS |\n| UI/data | Radix UI primitives, TanStack Query, TanStack Table, Zustand, Recharts, Lucide React |\n| Backend | Python 3.12, Flask, Flask-Cors, psycopg2 |\n| Database | PostgreSQL 17, SQL scripts, PL/pgSQL functions, triggers, views, indexes |\n| Local orchestration | Docker Compose |\n| Data generation | Python scripts with Faker |\n\n## Project Structure\n\n```text\ncefer/\n|-- client/                  # Next.js App Router frontend\n|   |-- app/                 # Role-based routes and pages\n|   |-- components/          # UI primitives and domain components\n|   |-- hooks/               # TanStack Query hooks and API wrappers\n|   `-- lib/                 # API client, auth state, query provider, utilities\n|-- server/                  # Flask and PostgreSQL backend\n|   |-- app/                 # App factory, routes, services, database session\n|   |-- data_generators/     # Synthetic data population modules\n|   |-- docker/              # Flask Dockerfile and entrypoint\n|   |-- scripts/             # Database population and downgrade helpers\n|   `-- sql/                 # Schema, SQL queries, views, indexes, functions\n|-- docs/                    # Operational documentation and course artifacts\n|-- LOGINS.md                # Seeded development credentials\n|-- relatorio.md             # Historical academic report artifact\n|-- docker-compose.yml       # Local full-stack orchestration\n`-- .env.example             # Environment variable template\n```\n\n## Documentation Map\n\n- [Documentation index](docs/index.md)\n- [Project overview](docs/overview.md)\n- [Architecture](docs/architecture.md)\n- [Setup](docs/setup.md)\n- [Development guide](docs/development.md)\n- [API reference](docs/api.md)\n- [Database guide](docs/database.md)\n- [Deployment notes](docs/deployment.md)\n- [Security notes](docs/security.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Client README](client/README.md)\n- [Server README](server/README.md)\n- [Seeded logins](LOGINS.md)\n\n## Prerequisites\n\nFor the Docker Compose workflow:\n\n- Docker\n- Docker Compose\n\nFor manual local development:\n\n- Node.js 20+\n- pnpm\n- Python 3.12+\n- PostgreSQL 17 or access to the Compose `postgres` service\n\n## Environment Configuration\n\nCopy `.env.example` to `.env` and adjust values as needed:\n\n```bash\ncp .env.example .env\n```\n\nImportant variables:\n\n| Variable | Purpose |\n| --- | --- |\n| `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `POSTGRES_PORT` | PostgreSQL container settings |\n| `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_SCHEMA` | Flask database connection settings |\n| `FLASK_SECRET_KEY` | Flask session signing secret |\n| `FLASK_DEBUG`, `FLASK_RUN_HOST`, `FLASK_RUN_PORT`, `FLASK_PORT` | Flask runtime and exposed port settings |\n| `NEXT_PUBLIC_API_URL` | Browser-visible base URL for the Flask API |\n| `NEXTJS_PORT`, `NODE_ENV` | Next.js runtime settings |\n| `CORS_ORIGINS` | Comma-separated allowed browser origins |\n| `POPULATE_DB` | Enables automatic database population in the Flask container |\n\nUse a strong `FLASK_SECRET_KEY` outside local coursework testing. Do not publish real database credentials.\n\n## Running With Docker Compose\n\nThe repository defines three services in `docker-compose.yml`:\n\n- `postgres`: PostgreSQL 17 with persisted data under `server/pgdata`.\n- `flask_app`: Flask API built from `server/docker/Dockerfile`.\n- `nextjs_app`: Next.js development server built from `client/Dockerfile.dev`.\n\nStart the stack:\n\n```bash\ndocker compose up -d\n```\n\nExpected local URLs with default `.env.example` values:\n\n- Frontend: \u003chttp://localhost:3000\u003e\n- Flask API: \u003chttp://localhost:5050\u003e\n- PostgreSQL: `localhost:5432`\n\nStop the stack:\n\n```bash\ndocker compose down\n```\n\nInspect logs:\n\n```bash\ndocker compose logs -f\ndocker compose logs -f flask_app\ndocker compose logs -f nextjs_app\ndocker compose logs -f postgres\n```\n\n## Manual Development Notes\n\nFrontend:\n\n```bash\ncd client\npnpm install\npnpm dev\n```\n\nBackend:\n\n```bash\ncd server\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\nflask run --host=0.0.0.0 --port=5050 --reload\n```\n\nThe Flask backend expects database variables from `.env`. For browser access, `NEXT_PUBLIC_API_URL` must point to the Flask API and `CORS_ORIGINS` must include the frontend origin.\n\n## Database Population\n\nThe database is database-first. Schema and application data are managed by SQL and Python generator assets:\n\n- `server/sql/upgrade_schema.sql`: main relational schema.\n- `server/sql/functions/`: PL/pgSQL auth, admin, staff, internal, and trigger functions.\n- `server/sql/views.sql`: reporting and table-view surfaces.\n- `server/sql/indexes.sql`: explicit indexes.\n- `server/data_generators/populate.py`: coordinated synthetic data population.\n- `server/data_generators/downgrade.py`: downgrade/cleanup path.\n\nWhen `POPULATE_DB=true`, the Flask container entrypoint checks whether the database is populated and runs the generator flow if needed.\n\nManual helper scripts:\n\n```bash\ncd server\n./scripts/populate_db.sh\n./scripts/downgrade_db.sh\n```\n\nSeeded accounts are documented in [LOGINS.md](LOGINS.md). They are development/coursework credentials only.\n\n## Available Scripts\n\nFrontend scripts in `client/package.json`:\n\n| Script | Purpose |\n| --- | --- |\n| `pnpm dev` | Starts the Next.js development server |\n| `pnpm build` | Builds the Next.js application |\n| `pnpm start` | Starts the production Next.js server |\n| `pnpm lint` | Runs ESLint |\n\nBackend helper scripts:\n\n| Script | Purpose |\n| --- | --- |\n| `server/scripts/populate_db.sh` | Applies schema assets and synthetic data |\n| `server/scripts/downgrade_db.sh` | Runs downgrade cleanup |\n\n## API Surface\n\nThe Flask API is grouped by blueprint:\n\n- `/auth`: login, registration, session inspection, password updates, registration approvals, external token login.\n- `/admin`: administrative dashboards and CRUD for users, installations, equipment, events, activities, and reservations.\n- `/internal`: internal-user dashboard, activity enrollment, reservations, equipment, and invitations.\n- `/staff`: staff dashboard, activity participant management, reservations, equipment and installation reservation management.\n- `/external`: external invite dashboard and invite accept/reject actions.\n- `/extension_group`: extension group management.\n- `/reports`: analytical report data.\n- `/views`: API access to SQL views.\n- `/debug`: database status, population, and cleanup helpers.\n\nSee [docs/api.md](docs/api.md) for the route map.\n\n## Tests\n\nNo active automated test setup was identified in the current codebase. There are no test scripts in `client/package.json`, no Python test framework configuration, and no test files found during this documentation pass. The client lockfile references `@playwright/test` through dependencies, but no Playwright project setup or script was identified.\n\n## Deployment Status\n\nThe repository contains Dockerfiles and Docker Compose configuration, but no CI/CD workflow, cloud hosting configuration, production release process, rollback process, or managed deployment target was identified.\n\nTreat the deployment assets as local/containerization support for the archived coursework unless they are revalidated and hardened.\n\n## Security Notes\n\n- Flask sessions depend on `FLASK_SECRET_KEY`.\n- API requests use cookies with `credentials: \"include\"` on the frontend.\n- Role checks are enforced with session-backed decorators in `server/app/services/auth/decorators.py`.\n- External users authenticate through invitation tokens stored in Flask session state.\n- CORS is controlled by `CORS_ORIGINS`.\n- Debug database routes exist under `/debug` and should not be exposed in a real production environment.\n- Seeded credentials in `LOGINS.md` are intentionally weak and must remain local-only.\n\nSee [docs/security.md](docs/security.md) for details.\n\n## Historical Academic Artifacts\n\nThe repository also contains course deliverables:\n\n- `relatorio.md`: Portuguese academic technical report.\n- `docs/entrega_final/`: final LaTeX/PDF deliverables.\n- `docs/entregas_parciais/`: partial course deliverables.\n- `docs/*.pdf`: original assignment or delivery PDFs.\n\nThese files are preserved as historical artifacts. They are not treated as living operational documentation in this refresh.\n\n## Current Status\n\nThis project is archived. The codebase remains useful for studying a full-stack, database-first academic application, but dependencies, Docker assumptions, credentials, debug routes, and deployment behavior should be reviewed before any reuse.\n\n## License\n\nTODO: not identified in the current codebase.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frckbrcls%2Fcefer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frckbrcls%2Fcefer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frckbrcls%2Fcefer/lists"}