docs: update documentation for recent features and fixes

Updated various markdown documentation files to reflect recent changes, including:
- Authenticated inline PDF opening and downloads.
- Improved grades PDF generation with null grade handling and bimester alignment.
- Filtering of all PDF reports by the current year.
- Frontend architectural changes: UserContext for state management, role-based UI adaptation, and middleware for route protection.
- Backend `TypeError` fix in grades PDF generation.
- Updates to development workflow and testing instructions, including the adoption of Biome for frontend linting and formatting.

Affected files:
- `README.md`
- `api/README.md`
- `app/README.md`
- `TESTING.md`
- `.github/CONTRIBUTING.md`

Author: Pinheiro-Reis

.github/CONTRIBUTING.md

@@ -74,12 +74,17 @@ We enforce a consistent code style using automated tools. Please run them before
 #### Frontend (TypeScript / Next.js)
 
 -   **Dependencies**: Managed with `npm` in `app/package.json`.
--   **Linting & Formatting**: We use **ESLint** with the `next/core-web-vitals` configuration. Run the linter to check for issues:
+-   **Linting & Formatting**: We use **Biome** for linting and formatting. Run the checker to identify issues:
     ```bash
     cd app/
-    npm run lint
+    npm run check
     ```
-    _We recommend integrating ESLint and a formatter like Prettier into your code editor to automatically format your code on save._
+    To automatically fix issues, run:
+    ```bash
+    cd app/
+    npm run check:write
+    ```
+    _We recommend integrating Biome into your code editor to automatically format and lint your code on save._
 
 ### API and Frontend Synchronization
 
@@ -105,6 +110,7 @@ Creste tests for all that you create (if applicable). Furthermore, reste the pro
     cd app/
     npm run test
     ```
+    Note: `npm run test` now includes automatic formatting and linting fixes via `biome check --write`.
 -   **End-to-End Testing**: The entire test suite (backend and frontend) can be run in a clean, containerized environment using the controller script. This is the same command our CI uses.
     ```bash
     ./controller.sh test
@@ -121,11 +127,11 @@ Once your changes are ready, follow these steps to submit a Pull Request.
 Before opening a PR, please ensure you have completed the following:
 
 -   [ ] All backend and frontend tests are passing (`./controller.sh test`).
--   [ ] The code is correctly formatted and passes all linter checks (`npm run lint`).
+-   [ ] The code is correctly formatted and passes all linter checks (`cd app/ && npm run check:write`).
 -   [ ] The application starts and runs without errors (`./controller.sh start`).
 -   [ ] You have written new tests for your changes.
 -   [ ] You have updated the [**README.md**](README.md) if you introduced changes to the interface, environment variables, or exposed ports.
--   [ ] You have documented significant changes in the [**NEW.md**](NEW.md) file.
+
 -   [ ] You have ensured that any new install or build dependencies are properly added to `pyproject.toml` or `package.json` and not left as local artifacts.
 
 ### Step 2: Open the Pull Request

README.md

@@ -49,6 +49,8 @@ Nginx acts as the entry point for all requests, directing them to the interface
 
 The interface consumes the Backend's REST API via `axios`. Check the URLs used by the Frontend in the [`config.ts`](./app/src/config.ts) file.
 
+For authenticated PDF downloads, the frontend now uses a dedicated utility (`openPdfInline`) that makes an authenticated `api.get` request to fetch the PDF content as a blob and then opens it in a new browser tab. This ensures secure access to sensitive documents.
+
 Therefore, the following Frontend excerpt, on the events page
 
 ```ts
@@ -109,6 +111,18 @@ and, if acquiring the data, stores it in the `data` variable, so that the data c
 
 The APP uses NextJS, a web framework, used in the construction of the components, together with React, as well as in the build function and to serve the static files.
 
+### User Context for State Management
+
+To centralize user data and roles, and to reduce redundant API calls, the application now utilizes a `UserContext`. This context provides a global state for the authenticated user's information, making it easily accessible across various components without prop drilling.
+
+### Middleware for Route Protection
+
+Sensitive routes and pages are protected by a Next.js middleware (`middleware.ts`). This middleware checks the user's authentication status and roles, redirecting unauthorized users or granting access based on defined permissions.
+
+### Dynamic Dashboard and UserInfoCard
+
+The Dashboard and `UserInfoCard` components have been rebuilt to dynamically adapt their content and functionality based on the authenticated user's role (e.g., Student, Guardian, Professor, Staff). This ensures a personalized and role-appropriate user experience.
+
 ### Endpoint Settings
 
 The API endpoint settings are defined in [`config.ts`](./app/src/config.ts).
@@ -188,7 +202,9 @@ Follow this pattern to avoid circular imports.
 
 There are functions in some serializers, which serve specific purposes, the so-called actions.
 
-When data related to some model is extracted, such as the grades of a certain student, it is recommended to use an action:
+When data related to some model is extracted, such as the grades of a certain student, it is recommended to use an action. The PDF generation for grades, presence, academic reports, and financial reports now filters data by the current year.
+
+Example of `download_grades_pdf` with improved logic:
 
 ```py
 . . .
@@ -199,11 +215,16 @@ class StudentViewSet(viewsets.ModelViewSet):
         student = self.get_object()
         subjects = get_subject_names()
         data = {}
+        current_year = timezone.now().year
+        all_grades = Grade.objects.filter(student=student, year=current_year)
+
         for subject in subjects:
-            data[subject] = Grade.objects.filter(
-                student=student,
-                subject__full_name=subject,
-            )
+            bimester_grades = [None, None, None, None]
+            for grade in all_grades.filter(subject__full_name=subject):
+                bimester_num = int(grade.bimester[0])
+                if 1 <= bimester_num <= 4:
+                    bimester_grades[bimester_num - 1] = grade.value
+            data[subject] = bimester_grades
         return pdfgen(
             "grades.html",
             {"student": student, "data": data},
@@ -311,7 +332,8 @@ POST /api/users/token/
 
 ### Frontend
 
--   Login is done through the `/auth/login` route, created by the [`login.ts`](<./app/src/app/(account)/auth/login/route.ts>) file, which sends the credentials to the backend and stores the tokens in cookies:
+-   Login is done through the `/auth/login` route, created by the [`login.ts`](<./app/src/app/(account)/auth/login/route.ts>) file, which sends the credentials to the backend and stores the tokens in cookies.
+-   The `UserContext` manages the authenticated user's state, including roles and permissions, making this information globally available across the application.
 -   The middleware ([`middleware.ts`](./app/src/middleware.ts)) protects sensitive routes:
 -   As long as the cookies persist, the user will remain authenticated even (except for the expiration policy configured in the Backend and cache cleaning).
 
@@ -391,14 +413,15 @@ Security is applied in the Backend, controlling access to each API endpoint base
             "academic_report",
             "download_academic_report",
             "students_needing_attention",
+            "efficiency_analysis",
         ]:
             self.permission_classes = [IsAuthenticated]
         else:
             self.permission_classes = [IsStaff]
         return super().get_permissions()
 ```
 
-Which defines the permission based on the action to be taken.
+Which defines the permission based on the action to be taken. Note that PDF generation actions (`download_grades_pdf`, `download_presence_pdf`, `download_academic_report`) are accessible to authenticated users, and these reports now filter data by the current year.
 
 ### User Structure
 

TESTING.md

@@ -34,6 +34,8 @@ cd app/
 npm run test
 ```
 
+Note: `npm run test` now includes automatic formatting fixes via `biome check --write`.
+
 ## Creating Tests
 
 ### API

api/README.md

@@ -153,12 +153,12 @@ Authorization: Bearer <your_token>
 -   `GET /api/students/{id}/` - Get student details
 -   `PUT /api/students/{id}/` - Update student (staff only)
 -   `DELETE /api/students/{id}/` - Delete student (staff only)
--   `GET /api/students/{id}/download-grades/` - Download student grades PDF
--   `GET /api/students/{id}/download-presence/` - Download student presence PDF
+-   `GET /api/students/{id}/download-grades/` - Download student grades PDF (data filtered by current year)
+-   `GET /api/students/{id}/download-presence/` - Download student presence PDF (data filtered by current year)
 -   `GET /api/students/{id}/academic-report/` - Get comprehensive academic report (JSON)
--   `GET /api/students/{id}/download-academic-report/` - Download academic report PDF
+-   `GET /api/students/{id}/download-academic-report/` - Download academic report PDF (data filtered by current year)
 -   `GET /api/students/students-needing-attention/` - List students needing notifications
--   `GET /api/students/efficiency-analysis/?year=2025` - Get global efficiency analysis (approval & dropout rates)
+-   `GET /api/students/efficiency-analysis/?year={year}` - Get global efficiency analysis (approval & dropout rates). The `year` parameter is optional and defaults to the current year.
 
 #### Grades (Notas)
 
@@ -219,7 +219,7 @@ Authorization: Bearer <your_token>
 -   `DELETE /api/students/tuitions/{id}/` - Delete tuition (staff only)
 -   `GET /api/students/tuitions/payment-history/?student_id={id}` - Get payment history
 -   `GET /api/students/tuitions/financial-report/?student_id={id}` - Get financial report
--   `GET /api/students/tuitions/download-financial-report/?student_id={id}` - Download financial report PDF
+-   `GET /api/students/tuitions/download-financial-report/?student_id={id}` - Download financial report PDF (data filtered by current year)
 
 #### Enrollments (Matrículas)
 

app/README.md

@@ -11,17 +11,36 @@ The frontend is built with Next.js and contains the following pages:
 ### Main
 
 - `/`: The main page of the application.
-- `/dashboard`: The user's dashboard.
+- `/dashboard`: The user's dashboard, which dynamically adapts its content and available actions based on the authenticated user's role (Student, Guardian, Professor, Staff).
 - `/agenda`: The agenda page.
 - `/events`: The events page.
 - `/inbox`: The user's inbox.
 - `/lessons`: The lessons page.
+- `/week-planning`: A professor-specific page for managing weekly lesson plans.
 - `/about`: The about page.
 
 ### Authentication
 
 - `/auth/login`: The login page.
 
+## Key Features and Components
+
+### User Context for Global State Management
+
+The application leverages a `UserContext` to manage the authenticated user's data and roles globally. This approach centralizes user information, making it readily available throughout the application and reducing the need for repetitive API calls or prop drilling.
+
+### Role-Based UI Adaptation
+
+Several key UI components, such as the `AppSidebar`, `UserInfoCard`, and the main Dashboard, are designed to dynamically adjust their display and functionality based on the authenticated user's role. This ensures a tailored and relevant user experience for Students, Guardians, Professors, and Staff members.
+
+### Authenticated PDF Handling
+
+A dedicated utility (`openPdfInline`) has been implemented to securely handle PDF documents. This utility makes authenticated requests to the backend to fetch PDF content as a blob and then opens it inline in a new browser tab, providing a seamless and secure viewing experience for reports and other documents.
+
+### Middleware for Route Protection
+
+Next.js middleware (`middleware.ts`) is used to enforce route protection. It intercepts requests to sensitive routes, verifies the user's authentication status and role, and grants or denies access accordingly. This ensures that users can only access the parts of the application they are authorized to see.
+
 ## API Routes
 
 The frontend also has the following API routes: