From b6f6d8619d1a7bb2a521ee53b7874c42d4a37449 Mon Sep 17 00:00:00 2001 From: lgr2002 Date: Sun, 19 Apr 2026 03:57:00 +1000 Subject: [PATCH 1/2] docs: add AI context guide for OnTrack --- src/content/docs/team/ai-context-guide.md | 129 ++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 src/content/docs/team/ai-context-guide.md diff --git a/src/content/docs/team/ai-context-guide.md b/src/content/docs/team/ai-context-guide.md new file mode 100644 index 00000000..96340c76 --- /dev/null +++ b/src/content/docs/team/ai-context-guide.md @@ -0,0 +1,129 @@ +--- +title: OnTrack AI Context File +description: Structured project context for use with AI tools such as GPT and Claude. +--- + + +## Project Summary + +OnTrack (formerly Doubtfire) is a student progress tracking and task management system used to manage learning activities, submissions, and tutor feedback. + +The system consists of: + +- Backend: Doubtfire API (REST API) +- Frontend: Doubtfire Web (Angular-based UI) +- Documentation: Astro + Starlight site + +--- + +## Key Repositories + +- doubtfire-api → backend REST API +- doubtfire-web → frontend application +- doubtfire-astro → documentation system + +--- + +## Tech Stack + +- Frontend: Angular +- Backend: Ruby on Rails (REST API) +- Documentation: Astro + Starlight +- Version Control: Git + GitHub + +--- + +## Backend API Overview + +The backend provides multiple REST APIs including: + +- auth → authentication and session management +- students → student data and progress +- tasks → task tracking and similarity checking +- projects → project management +- users → user accounts +- submissions → submission tracking +- units → unit and course structure + +All APIs follow REST conventions: + +- GET → retrieve data +- POST → create +- PUT → update +- DELETE → remove + +### Authentication + +APIs require: + +- `Username` (header) +- `Auth_Token` (header) + +### Example Endpoints + +- POST `/api/auth` → login +- GET `/api/students?unit_id=1` +- GET `/api/tasks?unit_id=1` + +--- + +## Frontend Overview + +The frontend provides user interfaces for tutors and admins. + +### Key Feature: Tutor Times + +The "Tutor Times" feature allows: + +#### Tutor View +- View marking sessions +- Track time spent on tasks +- View activity logs such as assessing and completed states +- Monitor progress across units + +#### Admin Dashboard +- View all tutor sessions +- Filter by tutor, unit, project, or date +- View aggregated marking statistics + +--- + +## Frontend Behaviour + +- Real-time session updates +- Activity tracking and logs +- Data visualisation using charts and graphs +- Responsive UI for desktop and mobile + +The UI includes: +- dashboards +- filters and sorting +- tables and graphs + +--- + +## Key Features + +### Core Features +- student progress tracking +- task and submission management +- unit and tutorial organisation + +### Frontend Features +- Tutor Times dashboard for tracking marking sessions +- Admin analytics dashboard with filtering and statistics +- Colour vision accessibility support with multiple display modes + +### Backend Features +- REST API for managing students, tasks, projects, and users +- authentication using Username and Auth_Token headers + +--- + +## Development Setup + +Run documentation site locally: + +```bash +npm install +npm run dev \ No newline at end of file From 9cb960b33c06a3f1cd21212f8184ae31282126ab Mon Sep 17 00:00:00 2001 From: lgr2002 Date: Tue, 19 May 2026 11:36:36 +0000 Subject: [PATCH 2/2] docs: add AI context and prompt guides --- src/content/docs/team/ai-context-guide.md | 432 ++++++++++++++---- .../docs/team/example-prompts-guide.md | 72 +++ 2 files changed, 426 insertions(+), 78 deletions(-) create mode 100644 src/content/docs/team/example-prompts-guide.md diff --git a/src/content/docs/team/ai-context-guide.md b/src/content/docs/team/ai-context-guide.md index 96340c76..7572f6f4 100644 --- a/src/content/docs/team/ai-context-guide.md +++ b/src/content/docs/team/ai-context-guide.md @@ -1,129 +1,405 @@ --- -title: OnTrack AI Context File -description: Structured project context for use with AI tools such as GPT and Claude. +title: OnTrack AI Context Guide +description: Reusable project and repository context for using AI tools with the OnTrack project. --- -## Project Summary -OnTrack (formerly Doubtfire) is a student progress tracking and task management system used to manage learning activities, submissions, and tutor feedback. +**Authors:** Jason Gilfoyle, Yeshin Govender, Leeon Gourav Rangey, Julian Mirchandani, Roeen Kareemy, Anagh Wadhwa -The system consists of: +--- + +## About OnTrack + +OnTrack is a learning management system used by universities including Deakin University. It allows students to submit tasks, track their progress, and receive feedback from tutors. + +Tutors and staff use the platform to manage units, review submissions, provide feedback, and monitor student performance. + +The project is maintained by Thoth Tech, a student-led development team at Deakin University. Development is split across multiple repositories covering frontend, backend, deployment, and documentation. + +Main repositories: -- Backend: Doubtfire API (REST API) -- Frontend: Doubtfire Web (Angular-based UI) -- Documentation: Astro + Starlight site +- `doubtfire-web` — Angular frontend +- `doubtfire-api` — Ruby on Rails backend +- `doubtfire-astro` — documentation site +- `doubtfire-deploy` — deployment configuration + +Current project work includes: + +- Migrating AngularJS components to Angular 17 +- Improving security +- Updating documentation +- Fixing bugs and improving usability --- -## Key Repositories +## Current Project Focus + +As of T1 2026, the OnTrack team is mainly focused on long-term improvements, security upgrades, and overall modernisation. + +### AngularJS to Angular 17 Migration + +The largest ongoing project is the gradual migration of the frontend from AngularJS and CoffeeScript to Angular 17 and TypeScript. + +The frontend currently contains: + +- Legacy AngularJS components +- Modern Angular 17 components + +Migration work is being completed incrementally to maintain compatibility and minimise disruption across the shared project architecture. + +Contributors should: + +- Use Angular 17 for new work +- Avoid creating new AngularJS components where possible +- Follow the existing project architecture +- Maintain compatibility with shared functionality + +### Security Improvements + +The project is also focused on improving overall security. + +Recent improvements include: + +- Migrating CI workflows to newer GitHub Actions versions +- Upgrading local development and CI environments to use a newer Node version +- Adding build verification during pull requests +- Improving dependency compatibility + +Future security work should aim to: + +- Identify and update outdated dependencies +- Modernise legacy tools where appropriate +- Reduce security risks by keeping software versions up to date +- Improve consistency between development environments + +### Documentation Improvements + +Documentation updates are also a major focus area for the team. Some documents were found to contain outdated or unnecessary information. -- doubtfire-api → backend REST API -- doubtfire-web → frontend application -- doubtfire-astro → documentation system +Current improvements include: + +- Expanding onboarding documentation for new contributors +- Improving local setup instructions +- Improving dev container workflows +- Reducing setup issues for new contributors --- -## Tech Stack +## Repository Overview + +The OnTrack project is split across four main repositories, each responsible for a different part of the system. + +- `doubtfire-web` — frontend web application +- `doubtfire-api` — Ruby on Rails backend API +- `doubtfire-astro` — documentation site +- `doubtfire-deploy` — deployment and Docker configuration -- Frontend: Angular -- Backend: Ruby on Rails (REST API) -- Documentation: Astro + Starlight -- Version Control: Git + GitHub +Each repository section below follows the same structure: + +- Purpose +- Tech Stack +- Important Files and Folders +- Common Contributor Tasks +- AI Should Be Careful About --- -## Backend API Overview +## Frontend Context: `doubtfire-web` -The backend provides multiple REST APIs including: +### Purpose -- auth → authentication and session management -- students → student data and progress -- tasks → task tracking and similarity checking -- projects → project management -- users → user accounts -- submissions → submission tracking -- units → unit and course structure +The `doubtfire-web` repository contains the frontend of the OnTrack learning management and feedback system. It is the user-facing part of the platform used by students, tutors, and admins. -All APIs follow REST conventions: +The frontend handles student, tutor, and admin interactions, including task submissions, feedback viewing, portfolio management, unit administration, file uploads, PDF previews, calendars, Gantt charts, QR code scanning, discussion prompts, emoji reactions, and comment interactions. -- GET → retrieve data -- POST → create -- PUT → update -- DELETE → remove +The frontend communicates with the `doubtfire-api` backend through proxy configuration files. The project is currently being migrated from the older AngularJS/CoffeeScript layer to Angular 17 and TypeScript. -### Authentication +### Tech Stack -APIs require: +The frontend uses a hybrid stack because the project is still being migrated. -- `Username` (header) -- `Auth_Token` (header) +Modern Angular layer: -### Example Endpoints +- Angular 17 +- TypeScript +- Angular Material +- RxJS +- Tailwind CSS +- Angular CLI -- POST `/api/auth` → login -- GET `/api/students?unit_id=1` -- GET `/api/tasks?unit_id=1` +Legacy AngularJS layer: ---- +- AngularJS 1.5 +- CoffeeScript +- Bootstrap 3 +- Grunt -## Frontend Overview +Testing and development tools: -The frontend provides user interfaces for tutors and admins. +- Karma and Jasmine +- ESLint and Prettier +- Husky and Commitlint -### Key Feature: Tutor Times +Other important libraries: -The "Tutor Times" feature allows: +- `ngx-entity-service` for structured API entity management +- `@uirouter/angular-hybrid` for routing +- `ng2-pdf-viewer` for PDF rendering +- `html5-qrcode` for QR code scanning +- `@worktile/gantt` for Gantt chart visualisation +- Monaco Editor for in-browser code editing -#### Tutor View -- View marking sessions -- Track time spent on tasks -- View activity logs such as assessing and completed states -- Monitor progress across units +### Important Files and Folders -#### Admin Dashboard -- View all tutor sessions -- Filter by tutor, unit, project, or date -- View aggregated marking statistics +Contributors working on the frontend should understand these areas: ---- +- `src/app/` — main application source code +- `src/app/tasks/` — task submissions, comments, and discussion features +- `src/app/projects/` — portfolio and project-related pages +- `src/app/units/` — unit and teaching period management +- `src/app/admin/` — admin-facing pages +- `src/app/errors/` — error and timeout handling +- `src/environments/` — environment configuration +- `src/assets/` — static assets and global styles +- `proxy.conf.json` — local backend API proxy configuration +- `proxy-compose.conf.json` — proxy configuration for Docker/local compose setup +- `angular.json` — Angular workspace and build configuration +- `Gruntfile.js` — legacy AngularJS build/watch configuration +- `package.json` — dependencies and development scripts +- `.eslintrc.json` — linting and formatting rules +- `.husky/` — Git hooks and commit message checks -## Frontend Behaviour +### Common Contributor Tasks -- Real-time session updates -- Activity tracking and logs -- Data visualisation using charts and graphs -- Responsive UI for desktop and mobile +Frontend contributors commonly work on: -The UI includes: -- dashboards -- filters and sorting -- tables and graphs +- Migrating AngularJS/CoffeeScript components to Angular 17 and TypeScript +- Updating UI components with Angular Material +- Replacing older Bootstrap 3 markup in migrated areas +- Creating or extending entity services +- Fixing frontend bugs in task, portfolio, unit, or admin pages +- Debugging hybrid routing issues +- Updating proxy configuration for local API calls +- Fixing ESLint and Prettier issues +- Writing or updating Karma/Jasmine unit tests +- Reviewing and resolving frontend pull request feedback +- Updating documentation when frontend conventions change + +### AI Should Be Careful About + +When using AI for frontend work, contributors should clearly mention whether they are working in the legacy AngularJS layer or the modern Angular layer. + +AI should be careful to: + +- Check whether the file is part of the legacy AngularJS/CoffeeScript layer or the modern Angular/TypeScript layer before generating code +- Avoid mixing AngularJS and Angular 17 patterns +- Avoid generating new CoffeeScript for new work +- Avoid generating standalone Angular components, because the project currently uses NgModule-based architecture +- Avoid using standard Angular Router assumptions, because the project uses `@uirouter/angular-hybrid` +- Avoid creating raw `HttpClient` calls if an existing `ngx-entity-service` pattern should be used +- Use Angular Material for modern UI work +- Use Tailwind only in modern Angular components +- Avoid suggesting Bootstrap 4 or Bootstrap 5, because the legacy layer uses Bootstrap 3 +- Follow RxJS patterns carefully and avoid memory leaks +- Ensure AI-generated code is reviewed, linted, tested, and checked against the existing repository structure +- Follow Conventional Commits format, because Husky and Commitlint enforce commit message rules --- -## Key Features +## Backend Context: `doubtfire-api` + +### Purpose + +The `doubtfire-api` repository contains the backend for OnTrack. It manages data persistence, business logic, authentication, and communication between the database and frontend interfaces through a RESTful API. -### Core Features -- student progress tracking -- task and submission management -- unit and tutorial organisation +### Tech Stack -### Frontend Features -- Tutor Times dashboard for tracking marking sessions -- Admin analytics dashboard with filtering and statistics -- Colour vision accessibility support with multiple display modes +- Ruby on Rails +- Ruby 3.1.0 +- REST API architecture +- Header-based authentication using user and token headers -### Backend Features -- REST API for managing students, tasks, projects, and users -- authentication using Username and Auth_Token headers +### Important Files and Folders + +Important backend areas include: + +- `doubtfire-api` — main backend repository containing server-side logic +- `/api/auth` — authentication endpoint used for login and token generation +- `/api/submissions` — endpoint area related to student submission retrieval and management +- Backend routes, controllers, and models should be checked before adding or changing API behaviour + +### Common Contributor Tasks + +Backend contributors commonly work on: + +- Updating or creating REST API endpoints +- Supporting frontend feature requirements +- Managing unit, student, task, and submission data +- Reviewing authentication and permission logic +- Testing backend behaviour +- Investigating security-related issues + +### AI Should Be Careful About + +AI should be careful to: + +- Include required authentication headers such as `X-Doubtfire-User` and `X-Doubtfire-Token` in request examples where needed +- Avoid inventing API endpoints without checking the actual routes +- Use correct REST methods: `GET` for reading, `POST` for creating, `PUT` for updating, and `DELETE` for removal +- Treat security-related suggestions as draft advice that must be manually reviewed and tested +- Check backend logic against existing Rails conventions before suggesting changes --- -## Development Setup +## Documentation Context: `doubtfire-astro` + +### Purpose + +The `doubtfire-astro` repository contains the OnTrack documentation site. It is used for contributor guides, onboarding information, project documentation, and support resources for the Thoth Tech team. + +### Tech Stack + +- Astro +- Starlight +- Markdown +- Node.js and npm +- Netlify deployment -Run documentation site locally: +### Important Files and Folders + +Documentation contributors should know: + +- `src/content/docs/` — main documentation page location +- Each page requires frontmatter fields such as `title` and `description` +- File structure affects page URLs and sidebar navigation +- Documentation pages are written in Markdown format + +### Common Contributor Tasks + +Documentation contributors commonly work on: + +- Creating or updating documentation pages +- Editing onboarding guides +- Updating project information +- Fixing formatting or broken links +- Running the documentation site locally + +Common local setup commands: ```bash npm install -npm run dev \ No newline at end of file +npm run dev +``` +--- +### AI Should Be Careful About + +AI should be careful to: + +- Keep Markdown formatting valid and consistent +- Avoid generating incorrect file paths or repository names +- Keep documentation aligned with the existing project structure +- Review generated commands and content before pushing changes +- Avoid adding unsupported formatting that may not work in Astro/Starlight + +--- + +## Deployment Context: `doubtfire-deploy` + +### Purpose + +The `doubtfire-deploy` repository contains the Docker-based configuration for running the full OnTrack stack locally and in production. It connects the Rails API, Angular frontend, PostgreSQL database, and RabbitMQ message broker. + +### Tech Stack + +- Docker +- Docker Compose +- Docker Desktop or Docker Engine on Linux +- PostgreSQL +- RabbitMQ +- Rails API service +- Angular frontend service + +### Important Files and Folders + +Important deployment files include: + +- `docker-compose.yml` — defines and orchestrates services in the stack +- `.env.example` — template for required environment variables +- Configuration files used to connect the frontend, backend, database, and message broker + +Key services in the compose configuration include: + +- `doubtfire-api` — Ruby on Rails backend +- `doubtfire-web` — Angular frontend +- PostgreSQL — primary relational database +- RabbitMQ — message broker used for background job processing + +### Common Contributor Tasks + +Deployment contributors commonly work on: + +- Updating service versions in the compose file +- Configuring environment variables for local development +- Troubleshooting port conflicts between services +- Verifying that API and frontend containers can communicate correctly +- Testing deployment changes before submitting a pull request + +### AI Should Be Careful About + +AI should be careful to: + +- Specify which service or container the issue relates to +- Include the exact error output from `docker compose logs` +- Avoid assuming the compose file structure matches generic Docker tutorials +- Check the actual repository configuration before suggesting changes +- Avoid exposing secrets or private environment values +- Remember that deployment changes can affect all contributors and should be reviewed carefully before merging + +- Remember that deployment changes can affect all contributors and should be reviewed carefully before merging + +--- + + + +## AI Usage Warnings + +AI tools such as ChatGPT, Claude, and Cursor can help contributors with debugging, documentation, code explanation, and code generation. However, AI-generated responses are not always accurate and should be reviewed carefully. + +The OnTrack project contains a hybrid architecture, so AI may misunderstand where legacy components still exist. + +Common AI mistakes may include: + +- Assuming the frontend is entirely Angular 17 +- Ignoring the presence of AngularJS +- Generating CoffeeScript where TypeScript should be used +- Confusing repository responsibilities +- Inventing file paths, APIs, components, or project rules + +AI-generated responses should be: + +- Reviewed manually +- Tested locally +- Formatted correctly +- Checked against the existing project structure +- Verified against repository conventions + +When using AI, contributors should: + +- Specify the repository name +- State whether the issue relates to frontend, backend, deployment, or documentation +- Include relevant code snippets +- Include exact error messages where possible +- Mention whether frontend code is Angular 17 or AngularJS +- Explain expected behaviour and actual behaviour +- Provide relevant file names or folder paths + +AI should assist contributor productivity, not replace contributor review. Contributors remain responsible for security validation, architecture decisions, code quality, testing, and final review. + +--- + +## Related Guide + +For reusable prompt templates and example prompts, see the separate Example Prompts Guide. + +This AI Context Guide focuses on project and repository context. The Example Prompts Guide focuses on how contributors can structure their questions when using AI tools. \ No newline at end of file diff --git a/src/content/docs/team/example-prompts-guide.md b/src/content/docs/team/example-prompts-guide.md new file mode 100644 index 00000000..c3ccf338 --- /dev/null +++ b/src/content/docs/team/example-prompts-guide.md @@ -0,0 +1,72 @@ +--- +title: Example Prompts Guide +description: Reusable prompt templates and examples for using AI tools with the OnTrack project. +--- + + + +This guide provides reusable prompt templates and examples for contributors using AI tools such as ChatGPT, Claude, Cursor, or similar tools while working on the OnTrack project. + +AI-generated output should always be reviewed, tested, and checked against the actual repository before being used. AI should support contributor work, not replace manual review, testing, or team approval. + +--- + +## Reusable Prompt Template + +Use this template when asking an AI tool for help with OnTrack work: + +```text +I am working on OnTrack, a learning management and feedback system maintained by Thoth Tech. + +The frontend is in the `doubtfire-web` repository and uses Angular 17, TypeScript, Angular Material, RxJS, and a legacy AngularJS/CoffeeScript layer. + +The backend is in the `doubtfire-api` repository and uses Ruby on Rails with REST API endpoints. + +The documentation site is in the `doubtfire-astro` repository and uses Astro, Starlight, and Markdown. + +I am currently working on [your specific task]. + +Here is the relevant file, code, error message, or context: +[paste details here] + +Can you help me [your specific request]? + +``` + + +## Backend Prompts + +- “I am working on the OnTrack back-end using Ruby on Rails. Can you help me implement a new API endpoint for retrieving submissions filtered by unit id?” +- “In OnTrack’s Rails back-end, how would I secure an endpoint so only authenticated users with a valid token can access it?” + +## Frontend Prompts + +- “In the OnTrack Angular frontend, how should I structure a service to call the `/api/tasks` endpoint and handle authentication headers?” +- “Can you help me build a component that displays student submissions and updates when new data is fetched from the API?” +- “I am working on the OnTrack frontend repository, `doubtfire-web`. The project is a hybrid frontend that is currently migrating from AngularJS/CoffeeScript to Angular 17 and TypeScript.” +- “Before helping, check whether the relevant file is in the legacy AngularJS layer or the modern Angular layer. New work should use Angular 17, TypeScript, Angular Material, RxJS, and the existing NgModule-based architecture. The project uses `@uirouter/angular-hybrid` for routing and `ngx-entity-service` patterns for API-related work.” +- “Please do not generate standalone Angular components, Angular RouterModule examples, Bootstrap 4/5 code, or raw `HttpClient` calls unless the existing project structure confirms they are needed.” + +## Migration Prompts + +- “What are best practices for migrating large AngularJS apps, such as OnTrack, to Angular 17 incrementally?” + +## Documentation Prompts + +- “I am working on the OnTrack documentation site using Astro and Starlight. Can you help me write a Markdown page explaining how to run the project locally?” +- “How should I structure documentation in `src/content/docs/` so it aligns with best practices for Astro and Starlight?” + +## Security Prompts + +- “OnTrack is focusing on fixing security issues. Can you review this API design and identify potential vulnerabilities related to authentication or data exposure?” +- “What are common security issues in Angular and Rails apps like OnTrack, and how can they be mitigated?” +- “I am working on the OnTrack Ruby on Rails backend. Using the Backend Context format, can you help me write a script that sends a `POST` request to `/api/auth` using the `X-Doubtfire-User` and `X-Doubtfire-Token` headers to test for a SQL injection auth bypass?” + +## Deployment Prompts + +- “I am working on the OnTrack deployment repo using Docker. Can you help me write a Docker configuration for running both the Rails backend and Angular frontend?” +- “How can I optimise Docker builds for a multi-repo project like OnTrack?” + +## Testing Prompts + +- “In Angular 17, how do I test a service that calls the OnTrack backend API?” \ No newline at end of file