chore: establish project maintenance baseline

.env.example

@@ -0,0 +1 @@
+GROQ_API_KEY=

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,57 @@
+name: Bug report
+description: Report a reproducible problem in EduAi
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Do not include API keys, credentials, student data, recordings, or
+        security vulnerabilities. Report vulnerabilities privately through the
+        repository Security page.
+  - type: textarea
+    id: description
+    attributes:
+      label: Problem
+      description: What happened, and what did you expect instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Start ...
+        2. Open ...
+        3. Select ...
+    validations:
+      required: true
+  - type: input
+    id: commit
+    attributes:
+      label: EduAi commit or version
+      description: A commit SHA is preferred.
+  - type: dropdown
+    id: component
+    attributes:
+      label: Affected component
+      options:
+        - Frontend
+        - Flask service
+        - Moodle backend
+        - Docker Compose or deployment
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include OS, browser, Docker version, and relevant service versions.
+  - type: textarea
+    id: logs
+    attributes:
+      label: Sanitized logs or screenshots
+      description: Remove all credentials and personal or student information.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security reporting guidance
+    url: https://github.com/NTNU-SoftwareEngineering/EduAi/blob/main/SECURITY.md
+    about: Read the private-reporting process before sharing vulnerability details.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,29 @@
+name: Feature request
+description: Propose a focused improvement to EduAi
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or learning need
+      description: Who is affected, and what are they unable to do today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed outcome
+      description: Describe the desired behavior without prescribing unnecessary implementation details.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: textarea
+    id: privacy
+    attributes:
+      label: Privacy, security, or deployment impact
+      description: Explain any new data, permissions, third-party services, or migration requirements.

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /frontend
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 3

.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Summary
+
+<!-- What problem does this change solve? -->
+
+## Validation
+
+<!-- List the commands and manual checks you ran. -->
+
+## Checklist
+
+- [ ] I kept this pull request focused on one change.
+- [ ] I tested the affected behavior or explained why it could not be tested.
+- [ ] I did not include credentials, student data, recordings, or other private data.
+- [ ] I updated documentation or screenshots when user-facing behavior changed.
+- [ ] My contribution is compatible with the repository's GPL-3.0 license.

.github/workflows/quality.yml

@@ -0,0 +1,60 @@
+name: Quality
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/quality.yml"
+      - ".env.example"
+      - "docker-compose.yml"
+      - "flask_server/**"
+      - "frontend/**"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/quality.yml"
+      - ".env.example"
+      - "docker-compose.yml"
+      - "flask_server/**"
+      - "frontend/**"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: quality-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  first-party-checks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend dependencies
+        run: npm ci --prefix frontend
+
+      - name: Check frontend syntax
+        run: npm run check --prefix frontend
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Check Python syntax
+        run: python -m compileall -q flask_server
+
+      - name: Validate Docker Compose configuration
+        run: |
+          cp .env.example .env
+          docker compose config --quiet

.gitignore

@@ -3,5 +3,4 @@ audio/*/*.wav
 .env
 .DS_Store
 .vscode/settings.json
-config.yml
-
+/config.yml

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to EduAi
+
+Thank you for helping improve EduAi. Contributions can include bug fixes,
+documentation, accessibility improvements, tests, and focused feature work.
+
+## Before starting
+
+1. Search the open issues and pull requests for existing work.
+2. Open an issue before a large feature, dependency migration, or architectural
+   change so maintainers and contributors can agree on scope.
+3. Keep each pull request focused on one independently reviewable change.
+
+The `moodle-backend/` directory is a vendored Moodle distribution. Avoid broad
+formatting or unrelated changes there. Moodle upgrades and Moodle-specific
+security fixes should be isolated from first-party application changes.
+
+## Development setup
+
+Follow the setup in [README.md](README.md). Copy `.env.example` to `.env` and
+keep API keys, passwords, student data, audio, and other private material out of
+Git. Use synthetic data in tests and screenshots.
+
+## Checks
+
+Before opening a pull request, run the checks relevant to your change:
+
+```sh
+npm ci --prefix frontend
+npm run check --prefix frontend
+python3 -m compileall -q flask_server
+cp .env.example .env
+docker compose config --quiet
+```
+
+If a check cannot run in your environment, explain why in the pull request and
+describe the validation you did perform.
+
+## Pull requests
+
+- Link the issue the pull request addresses, when one exists.
+- Explain the user-visible outcome and any migration or deployment impact.
+- Include screenshots for interface changes.
+- Add or update tests when behavior changes.
+- Do not commit generated secrets, credentials, personal information, student
+  records, or recordings.
+- Confirm that your contribution is compatible with this repository's
+  GPL-3.0 license.
+
+Dependency updates are proposed automatically by Dependabot. Maintainers still
+review release notes, compatibility, and test results before merging them.
+
+Maintainers may ask for changes to keep the project secure, reviewable, and
+consistent with its educational purpose.

README.md

@@ -1,50 +1,98 @@
-## EduAi
+# EduAi
 
-**EduAi** is a web application based on **Moodle** backend that allows teachers and students to access and manage their Moodle data through a web interface. It provides a user-friendly interface for students to view their **course information**, **discussion**, and even **interact with LLM**. <br><br>At the same time, **teachers** can upload **teaching plans**, get the **feedback**, and **analysis** of students' speech in the discussion. Which means teachers can easily understand the **students' learning status** and **adjust the teaching plan** in time.
+EduAi is a web application built around a Moodle backend. It gives students a
+simpler interface for course discussions and LLM-assisted conversations, while
+teachers can manage classes, upload teaching plans, and review learning
+feedback. The project originated in the 2024 NTNU Software Engineering course.
 
-This project is also derived from **NTNU Software Engineering Course**.
+> [!NOTE]
+> EduAi is an educational and research project. Review the example credentials,
+> API access, privacy requirements, and network exposure before deploying it
+> outside a local development environment.
 
-#### Features
+## Features
 
-- **Student Discussion**: View the current discussing problems in **real-time**, and analyze the speech of students with **speech-to-text** and LLM analysis.
-- **Conversation**: Interact with large language models (LLMs) to get answers to questions or generate content.
+- Real-time student discussions with speech-to-text and LLM analysis
+- Course-aware conversations with an LLM assistant
+- Class, group, question, and user management through Moodle
+- Teaching-plan upload and feedback
+- Student learning and discussion analysis
 
-- **Class Management**: Manage student **groups**, modify the **current question for discussion**, and get the **feedback** analyzed by **LLM** of the class.
-- **Teaching Plan**: Upload teaching plans, and get the **feedback** analyzed by **LLM**.
-- **Speech Analysis**: Analyze the speech of students in the discussion, and get the **feedback** analyzed by **LLM**.
-- **User Management**: Manage user information, including **username**, **fullname**, **email**, and **password**.
-- **Student Learning Analysis**: Analyze the learning status of students by **LLM**.
+![EduAi login screen](readme_assets/login.png)
 
+## Architecture
 
-#### Getting Started
+The repository contains these project services:
 
-![Login](readme_assets/login.png)
+| Service | Implementation | Default local URL |
+| --- | --- | --- |
+| Web application | Node.js and Express | <http://localhost:3000> |
+| Reverse proxy | Nginx | <http://localhost:8088> |
+| Learning platform | Moodle and Apache | <http://localhost:8080/moodle> |
+| Speech-to-text API | Python and Flask | <http://localhost:5001> |
+| Database administration | phpMyAdmin | <http://localhost:8081> |
 
-Developers or schools can easily build the server by **cloning** / **downloading** the whole repo, and run the server by 
-`docker compose up -d`
+The `moodle-backend/` directory is a vendored Moodle distribution. Project-
+specific application work normally belongs in `frontend/`, `flask_server/`,
+the Compose configuration, or project documentation.
 
-You can interact the frontend at `localhost:3000`
+## Getting started
 
-backstage management system will be at `localhost:8080/moodle`
+### Prerequisites
 
-#### Technology Stack
+- Git
+- Docker with Docker Compose v2
+- A Groq API key for LLM-backed features
 
-- **Frontend**: **Node.js**
-- **Backend**: **Moodle** + **Python Flask** 
-- **Database**: **MySQL**
-- **Speech-to-Text**: **Google Speech-to-Text API**
-- **LLM Analysis**: **Groq API**
+### Run the stack
 
+```sh
+git clone https://github.com/NTNU-SoftwareEngineering/EduAi.git
+cd EduAi
+cp .env.example .env
+```
 
-#### License
+Set `GROQ_API_KEY` in `.env`, then start the services:
 
-This project is licensed under the [Apache-2.0 License](LICENSE).
+```sh
+docker compose up -d --build
+```
 
-#### Contribution
+Open <http://localhost:3000>. Moodle administration is available at
+<http://localhost:8080/moodle>.
 
-Contributions are welcome! Please submit a pull request.
+To inspect startup problems:
 
-#### Contact
+```sh
+docker compose ps
+docker compose logs --tail=100
+```
 
-For any questions or issues, please open an issue. 
+Stop the stack without deleting database volumes:
 
+```sh
+docker compose down
+```
+
+## Local checks
+
+Run the same lightweight checks used by continuous integration:
+
+```sh
+npm ci --prefix frontend
+npm run check --prefix frontend
+python3 -m compileall -q flask_server
+cp .env.example .env
+docker compose config --quiet
+```
+
+## Contributing and security
+
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before
+opening a pull request. Automated dependency update proposals are configured
+through Dependabot. Please report vulnerabilities through the process in
+[SECURITY.md](SECURITY.md), not through a public issue.
+
+## License
+
+EduAi is licensed under the [GNU General Public License v3.0](LICENSE).