From 142a67025f7cbfe5cbc1be6e2b8c20a3ccad126b Mon Sep 17 00:00:00 2001 From: muhammadali-imran Date: Fri, 25 Sep 2026 20:24:19 +0500 Subject: [PATCH 1/4] root documents --- CODE_OF_CONDUCT.md | 52 +++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++ SECURITY.md | 34 ++++++++++++++++++++++ 3 files changed, 158 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..0d02698 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,52 @@ +# Code of Conduct + +## Our Pledge + +We are committed to building SignPakCommons as a respectful, inclusive, and collaborative project. We welcome contributors from all backgrounds, skill levels, and perspectives, and we expect all participation in this project to be constructive and professional. + +## Our Standards + +Examples of behavior that contributes to a positive environment include: + +- being kind, respectful, and patient with others +- giving and receiving feedback constructively +- focusing on the project goals, user impact, and technical quality +- acknowledging the work and effort of other contributors +- helping others learn and grow in a supportive way + +Examples of unacceptable behavior include: + +- harassment, intimidation, or personal attacks +- discriminatory, insulting, or exclusionary language +- threatening or abusive communication +- repeatedly derailing discussions or blocking progress without cause +- sharing private information without consent +- behavior that undermines the safety or dignity of contributors or users + +## Scope + +This Code of Conduct applies to all project spaces, including: + +- GitHub issues, pull requests, and discussions +- repository communication channels +- meetings, events, and project-related collaboration +- any public or private activity associated with SignPakCommons + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing this Code of Conduct. They may take any action they consider appropriate, including: + +- editing or removing harmful content +- asking for a change in behavior +- temporarily restricting participation +- removing access or banning contributors in serious or repeated cases + +## Reporting + +If you experience or witness unacceptable behavior, please report it privately to the project maintainers through the repository owner contact channels or the appropriate project communication route. Include as much context as possible, such as links, screenshots, dates, and the people involved. + +Reports will be reviewed promptly and handled confidentially, with a focus on maintaining a safe and respectful community. + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant and tailored to the SignPakCommons community. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1cca4b7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Contributing to SignPakCommons + +Thank you for your interest in contributing to SignPakCommons. This project exists to support Pakistan Sign Language data collection and accessibility work, and we value thoughtful, respectful contributions. + +## Ways to Contribute + +You can help in several ways: + +- report bugs or usability issues +- propose features or improvements +- improve documentation +- help with frontend or backend development +- improve testing or QA coverage +- contribute to data collection workflows and validation + +## Before You Start + +1. Read the project overview in [README.md](README.md). +2. Check the open issues and pull requests to avoid duplicating work. +3. Start with a small, focused change if you are new to the project. +4. Keep discussions respectful and grounded in the project mission and user impact. + +## Development Setup + +### Frontend + +```bash +cd frontend +npm install +npm run dev +``` + +### Backend + +```bash +cd backend +npm install +npm run dev +``` + +For local backend work, create the environment configuration required by the app before starting the server, using the sample environment file or setup notes in the backend documentation. + +## Contribution Workflow + +1. Fork the repository and create a branch for your work. +2. Make focused changes with clear commit messages. +3. Run the relevant checks for the area you modified. +4. Open a pull request with a clear description of the change and why it matters. +5. Be responsive to review feedback and update the PR as needed. + +## Pull Request Guidelines + +- Keep changes small and easy to review. +- Explain the problem being solved and the expected outcome. +- Include screenshots or examples when the change affects user-facing behavior. +- Update relevant documentation when the behavior or workflow changes. +- Ensure the code follows the project's existing patterns and conventions. + +## Coding Standards + +- Write readable, maintainable code. +- Prefer small, clear functions and simple logic. +- Follow the repo's existing style and naming conventions. +- Add or update tests when the change affects behavior. + +## Community Expectations + +Please read and follow the project's [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). We aim to make this a welcoming and productive environment for everyone. + +## Questions + +If you are unsure where to start, open an issue and ask. We are happy to help guide new contributors. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..069f17a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,34 @@ +# Security Policy + +## Supported Versions + +This project is under active development. Security updates are prioritized for the current main branch and any actively maintained release line. + +## Reporting a Vulnerability + +Please do not report security vulnerabilities through public issues or pull requests. + +If you believe you have found a security issue, report it privately to the maintainers through the repository owner contact channels or the project's private security reporting route. Please include: + +- a clear description of the vulnerability +- affected components or endpoints +- steps to reproduce the issue +- potential impact +- any suggested fix or mitigation + +## Response Expectations + +We will make our best effort to: + +- acknowledge valid reports promptly +- assess the severity and impact +- provide updates as the investigation progresses +- release a fix or mitigation as quickly as possible when needed + +## Responsible Disclosure + +We ask that reporters work with us to keep the issue private until a fix is available. Please do not disclose the vulnerability publicly before a coordinated resolution has been completed. + +## Scope + +This policy applies to security issues in the project codebase, configuration, deployment workflows, and project-maintained services related to SignPakCommons. From 9a3f4dbc4c486aa024b4e9bb4214d100e4b9fbf5 Mon Sep 17 00:00:00 2001 From: muhammadali-imran Date: Fri, 25 Sep 2026 20:25:53 +0500 Subject: [PATCH 2/4] new github template --- .github/ISSUE_TEMPLATE/bug_report.yml | 69 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/feature_request.yml | 53 +++++++++++++++++ .github/pull_request_template.md | 25 +++++++- 4 files changed, 145 insertions(+), 3 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..0b50175 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,69 @@ +name: Bug report +description: Report a bug or unexpected behavior in the project +title: "Bug Report" +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug. Please fill out the details below so we can investigate quickly. + + - type: input + id: summary + attributes: + label: Short summary + description: One-line description of the issue + placeholder: e.g. Login form fails on empty email + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: List the exact steps that cause the issue + placeholder: | + 1. Open the app + 2. Go to login + 3. Submit the form + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + placeholder: What should happen instead? + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + placeholder: What happened instead? + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Browser, OS, Node version, app route, or other relevant details + placeholder: | + - OS: + - Browser: + - Node version: + - App route: + - Build or branch: + validations: + required: false + + - type: textarea + id: logs + attributes: + label: Relevant logs or screenshots + description: Add console output, screenshots, or stack traces if available + placeholder: Paste logs or drag screenshots here + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..0086358 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..dd7de27 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,53 @@ +name: Feature request +description: Suggest a new feature or enhancement for the project +title: "Feature Request" +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting an improvement. Please describe the idea and its value clearly. + + - type: input + id: summary + attributes: + label: Feature summary + description: A brief title for the idea + placeholder: e.g. Add category filters to the library page + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem or need + description: What problem are you trying to solve? + placeholder: Describe the limitation or user need. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Explain the feature or workflow you want to add + placeholder: Describe the behavior or UI changes you expect. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + placeholder: What other approaches or workarounds have you considered? + validations: + required: false + + - type: textarea + id: context + attributes: + label: Additional context + description: Add screenshots, user stories, references, or implementation ideas + placeholder: Add any extra context here. + validations: + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ed8f90f..1df907d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,11 +1,30 @@ # Pull Request -## 📌 Summary +## Summary -Explain what this PR does and why. +Describe the purpose of this pull request and the problem it solves. -## 🛠️ Changes Made +## Changes made - [ ] Feature added - [ ] Bug fixed - [ ] Documentation updated +- [ ] Tests added or updated +- [ ] UI/UX changes +- [ ] Backend/API changes + +## Why this change is needed + +Explain the motivation, user impact, or issue being addressed. + +## Testing + +Describe how this was validated. + +- [ ] Manual testing completed +- [ ] Automated tests run +- [ ] No relevant tests were available + +## Notes + +Add any migration steps, follow-up tasks, screenshots, or blockers. From 6ca9fe2a30f30bb3a1e3bd54bae1cd6f684ed91e Mon Sep 17 00:00:00 2001 From: muhammadali-imran Date: Fri, 25 Sep 2026 20:27:22 +0500 Subject: [PATCH 3/4] frontend architecture doc --- frontend/docs/architecture.md | 214 ++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 frontend/docs/architecture.md diff --git a/frontend/docs/architecture.md b/frontend/docs/architecture.md new file mode 100644 index 0000000..020f76c --- /dev/null +++ b/frontend/docs/architecture.md @@ -0,0 +1,214 @@ +# Frontend Architecture + +## Purpose + +This frontend is a React application for SignPakCommons, a video data collection and contributor workflow. The app supports public browsing, authenticated contributor flows, recording and submission, admin management, and SEO-friendly static pages. + +The project uses: + +- React 19 +- Vite +- Tailwind CSS v4 +- React Router +- Context-based state management + +## Runtime Architecture + +### 1. App bootstrap + +The application starts in `src/main.jsx`. + +- Wraps the app in `ThemeProvider` +- Mounts the app inside `BrowserRouter` +- Installs the authentication, notification, library, and recording providers in nested order +- Renders the root app component + +This pattern keeps global app state centralized and predictable while preserving a simple top-level composition model. + +### 2. Route composition + +The route tree lives in `src/App.jsx`. + +The app uses nested route groups: + +- Public routes: landing, demo, FAQ, login, signup +- Authenticated contributor routes: home, library, watch, profile, editor +- Admin-only routes: dashboard, video management, category management + +Access control is enforced by route guards: + +- `RequireAuth` redirects unauthenticated users to login +- `RequireAdmin` restricts admin-only screens +- `GuestOnly` prevents signed-in users from visiting login/signup flows again + +This keeps screen-level permissions declarative and consistent across the UI. + +## State Management + +The app relies primarily on React context providers instead of a full external state library. + +### Auth + +- `src/context/AuthContext.js` +- `src/context/AuthProvider.jsx` + +Owns user session state, auth checks, loading state, and admin status. UI route guards read directly from this context. + +### Library + +- `src/context/LibraryContext.js` +- `src/context/LibraryProvider.jsx` + +Tracks the category/video browsing workflow and related UI state. + +### Recording + +- `src/context/RecordingContext.js` +- `src/context/RecordingProvider.jsx` + +Controls recording-session state, playback/editing flow, and submission-related UI state. + +### Notifications + +- `src/context/NotificationContext.js` +- `src/context/NotificationProvider.jsx` + +Handles per-user notifications and read state, mirroring the local persistence pattern used elsewhere in the app. + +### Theme + +- `src/context/ThemeContext.js` +- `src/context/ThemeProvider.jsx` + +Manages light/dark mode and persists user preference with local storage while honoring the OS preference on first load. + +## UI and Layout Structure + +### Shared shell + +The app uses a shared layout system from `src/components/Layouts.jsx` and a set of reusable pieces such as: + +- `Header` +- `Footer` +- `AuthShell` +- `NotificationBell` +- `ThemeToggle` +- `RouteGuards` +- UI primitives like `Field`, `PageState`, and `ButtonLink` + +This keeps navigation, auth framing, and page-level chrome consistent across route groups. + +### Page organization + +Pages are organized by feature: + +- `src/pages/` for public and user-facing views +- `src/pages/admin/` for admin screens and nested admin layout + +Examples: + +- `Landing`, `Demo`, `Faq` +- `Login`, `Signup`, `Home` +- `CategoryBrowser`, `Player`, `RecordingEditor`, `ProfileDashboard` +- `AdminDashboard`, `AdminVideos`, `AdminCategories` + +Each page is mostly self-contained and uses shared providers and reusable UI primitives instead of a large global component tree. + +## Data Flow + +The frontend is designed around a service boundary rather than direct fetch calls scattered across components. + +### Service layer + +The project expects data access to happen through service modules under `src/services/`. + +That boundary is important because the app currently contains mock/local behavior while the backend is still being integrated. In practice, the app intentionally centralizes access patterns so that the UI layer does not care whether the source is mock storage, local storage, or a live API. + +### Mock-first strategy + +This frontend is currently built with a mock data model and browser persistence patterns, including: + +- localStorage for session and preferences +- IndexedDB for generated or uploaded local media assets +- in-browser mock API behavior for likes, submissions, and demo data + +This keeps the UX functional without a backend, which is useful for product iteration and UI validation. + +## Styling Architecture + +The app uses Tailwind CSS with semantic component classes and theme tokens rather than scattered raw color literals. + +### Design approach + +- Utility classes are not the primary pattern for this app +- CSS is organized around semantic selectors such as `.btn`, `.lesson-card`, `.recorder`, and theme-related tokens +- The app uses CSS custom properties to support light/dark mode +- Theme values are centralized and switchable from a single theme definition + +This makes style updates easier and reduces the risk of inconsistent colors or mismatched ui states. + +## SEO and static generation + +The frontend includes dedicated SEO support under `src/seo/` and scripts in the project root of the frontend. + +### SEO flow + +- `src/seo/seoCatalog.mjs` defines public routes and metadata +- `scripts/generateSeoAssets.js` generates assets like `sitemap.xml` and `robots.txt` +- `npm run seo:generate` runs before build +- `npm run snap` can prerender pages for static HTML output + +This architecture supports discoverability and strong initial metadata for public pages while keeping route metadata data-driven. + +## Routing and URL conventions + +The app uses path-based navigation and query-string IDs for media items. + +Examples: + +- `/` landing page +- `/demo` walkthrough page +- `/home` contributor dashboard +- `/library/:categoryId` category browsing +- `/watch?v=` media playback +- `/watch/edit?v=` editing flow +- `/admin` admin dashboard + +This design separates content identity from route structure, making links less brittle as categories or catalog ordering change. + +## Folder Map + +```text +frontend/ + src/ + App.jsx # route layout and screen composition + main.jsx # app bootstrap and provider nesting + components/ # reusable UI and layout pieces + context/ # global state providers + hooks/ # custom React hooks + pages/ # route-level screens + pages/admin/ # admin screens + routes/ # route helpers and path definitions + services/ # API/service boundary + seo/ # metadata and SEO catalog + styles/ # theme and shared CSS + utils/ # helpers and shared utilities + mock/ # demo data and local-generated state + docs/ + architecture.md # this document + scripts/ + generateSeoAssets.js + runReactSnap.js +``` + +## Architectural Principles + +1. Keep route-level access logic declarative with guards. +2. Keep global app state in context providers instead of prop drilling. +3. Centralize backend communication behind service boundaries. +4. Keep shared UI and theme tokens reusable across screens. +5. Separate navigation, content state, and provider orchestration so the app is easy to evolve. + +## Summary + +The frontend is a modular React application organized around a clear provider-based state model, route-driven screens, reusable UI shells, and a mock-first data layer. Its architecture is intentionally structured so it can evolve from a browser-only prototype into a real backend-backed app without major changes to the screen composition or route design. From 287de74e1ca1ab32315a1f7aacd06f6944a52e35 Mon Sep 17 00:00:00 2001 From: muhammadali-imran Date: Fri, 25 Sep 2026 22:13:20 +0500 Subject: [PATCH 4/4] fix --- frontend/src/pages/admin/AdminDashboard.jsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/pages/admin/AdminDashboard.jsx b/frontend/src/pages/admin/AdminDashboard.jsx index d84b1e0..344794f 100644 --- a/frontend/src/pages/admin/AdminDashboard.jsx +++ b/frontend/src/pages/admin/AdminDashboard.jsx @@ -129,7 +129,7 @@ export default function AdminDashboard() {
    - {perCategory.length ? perCategory.map(({ category, count, totalVideos }) =>
  • {category.label}
    {count}
    • ) :
  • No categories yet.
    • } + {perCategory.length ? perCategory.map(({ category, count }) =>
  • {category.label}
    {count}
    • ) :
  • No categories yet.
    • }

{selectedCategory === 'all' ? 'This shows the category mix across the selected range.' : `Category focus: ${categories.find((entry) => entry.id === selectedCategory)?.label || 'Selected category'}.`}