# AGENTS.md

## Project Overview

This is an educational curriculum repository for teaching web development fundamentals to beginners. The curriculum is a comprehensive 12-week course developed by Microsoft Cloud Advocates, featuring 24 hands-on lessons covering JavaScript, CSS, and HTML.

### Key Components

- **Educational Content**: 24 structured lessons organized into project-based modules
- **Practical Projects**: Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor, and AI Chat Assistant
- **Interactive Quizzes**: 48 quizzes with 3 questions each (pre/post-lesson assessments)
- **Multi-language Support**: Automated translations for 50+ languages via GitHub Actions
- **Technologies**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (for AI projects)

### Architecture

- Educational repository with lesson-based structure
- Each lesson folder contains README, code examples, and solutions
- Standalone projects in separate directories (quiz-app, various lesson projects)
- Translation system using GitHub Actions (co-op-translator)
- Documentation served via Docsify and available as PDF

## Setup Commands

This repository is primarily for educational content consumption. For working with specific projects:

### Main Repository Setup

```bash
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
```

### Quiz App Setup (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint
```

### Bank Project API (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier
```

### Browser Extension Projects

```bash
cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions
```

### Space Game Projects

```bash
cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server
```

### Chat Project (Python Backend)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py
```

## Development Workflow

### For Content Contributors

1. **Fork the repository** to your GitHub account
2. **Clone your fork** locally
3. **Create a new branch** for your changes
4. Make changes to lesson content or code examples
5. Test any code changes in relevant project directories
6. Submit pull requests following contribution guidelines

### For Learners

1. Fork or clone the repository
2. Navigate to lesson directories sequentially
3. Read README files for each lesson
4. Complete pre-lesson quizzes at https://ff-quizzes.netlify.app/web/
5. Work through code examples in lesson folders
6. Complete assignments and challenges
7. Take post-lesson quizzes

### Live Development

- **Documentation**: Run `docsify serve` in root (port 3000)
- **Quiz App**: Run `npm run dev` in quiz-app directory
- **Projects**: Use VS Code Live Server extension for HTML projects
- **API Projects**: Run `npm start` in respective API directories

## Testing Instructions

### Quiz App Testing

```bash
cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds
```

### Bank API Testing

```bash
cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors
```

### General Testing Approach

- This is an educational repository without comprehensive automated tests
- Manual testing focuses on:
  - Code examples run without errors
  - Links in documentation work correctly
  - Project builds complete successfully
  - Examples follow best practices

### Pre-submission Checks

- Run `npm run lint` in directories with package.json
- Verify markdown links are valid
- Test code examples in browser or Node.js
- Check that translations maintain proper structure

## Code Style Guidelines

### JavaScript

- Use modern ES6+ syntax
- Follow standard ESLint configurations provided in projects
- Use meaningful variable and function names for educational clarity
- Add comments explaining concepts for learners
- Format using Prettier where configured

### HTML/CSS

- Semantic HTML5 elements
- Responsive design principles
- Clear class naming conventions
- Comments explaining CSS techniques for learners

### Python

- PEP 8 style guidelines
- Clear, educational code examples
- Type hints where helpful for learning

### Markdown Documentation

- Clear heading hierarchy
- Code blocks with language specification
- Links to additional resources
- Screenshots and images in `images/` directories
- Alt text for images for accessibility

### File Organization

- Lessons numbered sequentially (1-getting-started-lessons, 2-js-basics, etc.)
- Each project has `solution/` and often `start/` or `your-work/` directories
- Images stored in lesson-specific `images/` folders
- Translations in `translations/{language-code}/` structure

## Build and Deployment

### Quiz App Deployment (Azure Static Web Apps)

The quiz-app is configured for Azure Static Web Apps deployment:

```bash
cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main
```

Azure Static Web Apps configuration:
- **App location**: `/quiz-app`
- **Output location**: `dist`
- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### Documentation PDF Generation

```bash
npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs
```

### Docsify Documentation

```bash
npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000
```

### Project-specific Builds

Each project directory may have its own build process:
- Vue projects: `npm run build` creates production bundles
- Static projects: No build step, serve files directly

## Pull Request Guidelines

### Title Format

Use clear, descriptive titles indicating the area of change:
- `[Quiz-app] Add new quiz for lesson X`
- `[Lesson-3] Fix typo in terrarium project`
- `[Translation] Add Spanish translation for lesson 5`
- `[Docs] Update setup instructions`

### Required Checks

Before submitting a PR:

1. **Code Quality**:
   - Run `npm run lint` in affected project directories
   - Fix all linting errors and warnings

2. **Build Verification**:
   - Run `npm run build` if applicable
   - Ensure no build errors

3. **Link Validation**:
   - Test all markdown links
   - Verify image references work

4. **Content Review**:
   - Proofread for spelling and grammar
   - Ensure code examples are correct and educational
   - Verify translations maintain original meaning

### Contribution Requirements

- Agree to Microsoft CLA (automated check on first PR)
- Follow the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
- See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines
- Reference issue numbers in PR description if applicable

### Review Process

- PRs reviewed by maintainers and community
- Educational clarity is prioritized
- Code examples should follow current best practices
- Translations reviewed for accuracy and cultural appropriateness

## Translation System

### Automated Translation

- Uses GitHub Actions with co-op-translator workflow
- Translates to 50+ languages automatically
- Source files in main directories
- Translated files in `translations/{language-code}/` directories

### Adding Manual Translation Improvements

1. Locate file in `translations/{language-code}/`
2. Make improvements while preserving structure
3. Ensure code examples remain functional
4. Test any localized quiz content

### Translation Metadata

Translated files include metadata header:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

## Debugging and Troubleshooting

### Common Issues

**Quiz app fails to start**:
- Check Node.js version (v14+ recommended)
- Delete `node_modules` and `package-lock.json`, run `npm install` again
- Check for port conflicts (default: Vite uses port 5173)

**API server won't start**:
- Verify Node.js version meets minimum (node >=10)
- Check if port is already in use
- Ensure all dependencies installed with `npm install`

**Browser extension won't load**:
- Verify manifest.json is properly formatted
- Check browser console for errors
- Follow browser-specific extension installation instructions

**Python chat project issues**:
- Ensure OpenAI package installed: `pip install openai`
- Verify GITHUB_TOKEN environment variable is set
- Check GitHub Models access permissions

**Docsify not serving docs**:
- Install docsify-cli globally: `npm install -g docsify-cli`
- Run from repository root directory
- Check that `docs/_sidebar.md` exists

### Development Environment Tips

- Use VS Code with Live Server extension for HTML projects
- Install ESLint and Prettier extensions for consistent formatting
- Use browser DevTools for debugging JavaScript
- For Vue projects, install Vue DevTools browser extension

### Performance Considerations

- Large number of translated files (50+ languages) means full clones are large
- Use shallow clone if only working on content: `git clone --depth 1`
- Exclude translations from searches when working on English content
- Build processes may be slow on first run (npm install, Vite build)

## Security Considerations

### Environment Variables

- API keys should never be committed to repository
- Use `.env` files (already in `.gitignore`)
- Document required environment variables in project READMEs

### Python Projects

- Use virtual environments: `python -m venv venv`
- Keep dependencies updated
- GitHub tokens should have minimal required permissions

### GitHub Models Access

- Personal Access Tokens (PAT) required for GitHub Models
- Tokens should be stored as environment variables
- Never commit tokens or credentials

## Additional Notes

### Target Audience

- Complete beginners to web development
- Students and self-learners
- Teachers using the curriculum in classrooms
- Content is designed for accessibility and gradual skill building

### Educational Philosophy

- Project-based learning approach
- Frequent knowledge checks (quizzes)
- Hands-on coding exercises
- Real-world application examples
- Focus on fundamentals before frameworks

### Repository Maintenance

- Active community of learners and contributors
- Regular updates to dependencies and content
- Issues and discussions monitored by maintainers
- Translation updates automated via GitHub Actions

### Related Resources

- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) recommended for learners
- Additional courses: Generative AI, Data Science, ML, IoT curricula available

### Working with Specific Projects

For detailed instructions on individual projects, refer to the README files in:
- `quiz-app/README.md` - Vue 3 quiz application
- `7-bank-project/README.md` - Banking application with authentication
- `5-browser-extension/README.md` - Browser extension development
- `6-space-game/README.md` - Canvas-based game development
- `9-chat-project/README.md` - AI chat assistant project

### Monorepo Structure

While not a traditional monorepo, this repository contains multiple independent projects:
- Each lesson is self-contained
- Projects don't share dependencies
- Work on individual projects without affecting others
- Clone entire repo for the full curriculum experience

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Disclaimer**:
This document has been translated using AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->