CONTRIBUTING.md

Contributing to EcoGuide AI

Thank you for your interest in contributing! This document explains how to get started.

Getting Started

1. Fork the repository and clone your fork
2. Install dependencies: npm install in both backend/ and frontend/
3. Copy .env.example to .env in both directories and fill in values
4. Run migrations: cd backend && npx prisma migrate deploy
5. Start dev servers: npm run dev in each directory

Development Workflow

• Branch from main with a descriptive name: feat/my-feature or fix/my-bug
• Keep commits focused and use conventional commit messages:
  • feat: new feature
  • fix: bug fix
  • security: security improvement
  • perf: performance improvement
  • test: test addition or update
  • docs: documentation update
  • chore: tooling/config change

Code Standards

• No var — use const / let
• Strict equality — use === everywhere
• No console in production — use src/utils/logger.js in frontend
• Sanitize all inputs — use src/utils/sanitize.js for numeric/text fields
• JSDoc — add JSDoc to all exported functions in services/ and utils/
• Run npm run lint before opening a PR — zero warnings expected

Testing

All new features must include tests:

cd backend && npm test
cd frontend && npm test

• Backend: add tests in backend/src/tests/unit/
• Frontend utilities: add tests in frontend/src/tests/
• Aim for >90% coverage on utility functions

Pull Request Checklist

• Tests pass locally (npm test in both directories)
• No ESLint warnings (npm run lint)
• No hardcoded secrets or API keys
• JSDoc added to new functions
• README updated if adding new env vars or features

Reporting Issues

Please open a GitHub Issue with:

• Steps to reproduce
• Expected vs. actual behaviour
• Browser/Node.js version

Assumptions & Anonymous Sessions

EcoGuide AI operates without user accounts. This means:

• Session identity is an anonymous UUID generated on first visit and stored in localStorage. Clearing browser storage is equivalent to "logging out".
• Cross-device: There is no sync across devices. Each browser gets its own independent session UUID and history.
• No authentication: The backend accepts any UUID as a userId. The POST /api/assessments endpoint auto-creates a placeholder user record if the UUID is unknown (e.g. after a DB wipe or first use), so data is never silently lost.
• Synthetic emails: When the backend creates a placeholder user it generates ${uuid}@ecoguide.ai as a unique DB key. This is never used for email communication — it exists only to satisfy the database unique constraint.
• Privacy by design: No names, real emails, or personally identifiable information are collected at any point. All data can be cleared by the user at any time through browser storage settings.

If you extend the platform to support real accounts (e.g. OAuth), update the useUser hook, the /api/users route, and the Prisma User model — and remove the synthetic email fallback in assessmentService.js.

License

By contributing, you agree your contributions will be licensed under the MIT License.