AGENTS.md

1# AGENTS.md
2 
3## Project Overview
4 
5This 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.
6 
7### Key Components
8 
9- **Educational Content**: 24 structured lessons organized into project-based modules
10- **Practical Projects**: Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor, and AI Chat Assistant
11- **Interactive Quizzes**: 48 quizzes with 3 questions each (pre/post-lesson assessments)
12- **Multi-language Support**: Automated translations for 50+ languages via GitHub Actions
13- **Technologies**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (for AI projects)
14 
15### Architecture
16 
17- Educational repository with lesson-based structure
18- Each lesson folder contains README, code examples, and solutions
19- Standalone projects in separate directories (quiz-app, various lesson projects)
20- Translation system using GitHub Actions (co-op-translator)
21- Documentation served via Docsify and available as PDF
22 
23## Setup Commands
24 
25This repository is primarily for educational content consumption. For working with specific projects:
26 
27### Main Repository Setup
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Quiz App Setup (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Start development server
40npm run build      # Build for production
41npm run lint       # Run ESLint
42```
43 
44### Bank Project API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Start API server
50npm run lint       # Run ESLint
51npm run format     # Format with Prettier
52```
53 
54### Browser Extension Projects
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Follow browser-specific extension loading instructions
60```
61 
62### Space Game Projects
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Open index.html in browser or use Live Server
68```
69 
70### Chat Project (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Set GITHUB_TOKEN environment variable
76python api.py
77```
78 
79## Development Workflow
80 
81### For Content Contributors
82 
831. **Fork the repository** to your GitHub account
842. **Clone your fork** locally
853. **Create a new branch** for your changes
864. Make changes to lesson content or code examples
875. Test any code changes in relevant project directories
886. Submit pull requests following contribution guidelines
89 
90### For Learners
91 
921. Fork or clone the repository
932. Navigate to lesson directories sequentially
943. Read README files for each lesson
954. Complete pre-lesson quizzes at https://ff-quizzes.netlify.app/web/
965. Work through code examples in lesson folders
976. Complete assignments and challenges
987. Take post-lesson quizzes
99 
100### Live Development
101 
102- **Documentation**: Run `docsify serve` in root (port 3000)
103- **Quiz App**: Run `npm run dev` in quiz-app directory
104- **Projects**: Use VS Code Live Server extension for HTML projects
105- **API Projects**: Run `npm start` in respective API directories
106 
107## Testing Instructions
108 
109### Quiz App Testing
110 
111```bash
112cd quiz-app
113npm run lint       # Check for code style issues
114npm run build      # Verify build succeeds
115```
116 
117### Bank API Testing
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Check for code style issues
122node server.js     # Verify server starts without errors
123```
124 
125### General Testing Approach
126 
127- This is an educational repository without comprehensive automated tests
128- Manual testing focuses on:
129  - Code examples run without errors
130  - Links in documentation work correctly
131  - Project builds complete successfully
132  - Examples follow best practices
133 
134### Pre-submission Checks
135 
136- Run `npm run lint` in directories with package.json
137- Verify markdown links are valid
138- Test code examples in browser or Node.js
139- Check that translations maintain proper structure
140 
141## Code Style Guidelines
142 
143### JavaScript
144 
145- Use modern ES6+ syntax
146- Follow standard ESLint configurations provided in projects
147- Use meaningful variable and function names for educational clarity
148- Add comments explaining concepts for learners
149- Format using Prettier where configured
150 
151### HTML/CSS
152 
153- Semantic HTML5 elements
154- Responsive design principles
155- Clear class naming conventions
156- Comments explaining CSS techniques for learners
157 
158### Python
159 
160- PEP 8 style guidelines
161- Clear, educational code examples
162- Type hints where helpful for learning
163 
164### Markdown Documentation
165 
166- Clear heading hierarchy
167- Code blocks with language specification
168- Links to additional resources
169- Screenshots and images in `images/` directories
170- Alt text for images for accessibility
171 
172### File Organization
173 
174- Lessons numbered sequentially (1-getting-started-lessons, 2-js-basics, etc.)
175- Each project has `solution/` and often `start/` or `your-work/` directories
176- Images stored in lesson-specific `images/` folders
177- Translations in `translations/{language-code}/` structure
178 
179## Build and Deployment
180 
181### Quiz App Deployment (Azure Static Web Apps)
182 
183The quiz-app is configured for Azure Static Web Apps deployment:
184 
185```bash
186cd quiz-app
187npm run build      # Creates dist/ folder
188# Deploys via GitHub Actions workflow on push to main
189```
190 
191Azure Static Web Apps configuration:
192- **App location**: `/quiz-app`
193- **Output location**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Documentation PDF Generation
197 
198```bash
199npm install                    # Install docsify-to-pdf
200npm run convert               # Generate PDF from docs
201```
202 
203### Docsify Documentation
204 
205```bash
206npm install -g docsify-cli    # Install Docsify globally
207docsify serve                 # Serve on localhost:3000
208```
209 
210### Project-specific Builds
211 
212Each project directory may have its own build process:
213- Vue projects: `npm run build` creates production bundles
214- Static projects: No build step, serve files directly
215 
216## Pull Request Guidelines
217 
218### Title Format
219 
220Use clear, descriptive titles indicating the area of change:
221- `[Quiz-app] Add new quiz for lesson X`
222- `[Lesson-3] Fix typo in terrarium project`
223- `[Translation] Add Spanish translation for lesson 5`
224- `[Docs] Update setup instructions`
225 
226### Required Checks
227 
228Before submitting a PR:
229 
2301. **Code Quality**:
231   - Run `npm run lint` in affected project directories
232   - Fix all linting errors and warnings
233 
2342. **Build Verification**:
235   - Run `npm run build` if applicable
236   - Ensure no build errors
237 
2383. **Link Validation**:
239   - Test all markdown links
240   - Verify image references work
241 
2424. **Content Review**:
243   - Proofread for spelling and grammar
244   - Ensure code examples are correct and educational
245   - Verify translations maintain original meaning
246 
247### Contribution Requirements
248 
249- Agree to Microsoft CLA (automated check on first PR)
250- Follow the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines
252- Reference issue numbers in PR description if applicable
253 
254### Review Process
255 
256- PRs reviewed by maintainers and community
257- Educational clarity is prioritized
258- Code examples should follow current best practices
259- Translations reviewed for accuracy and cultural appropriateness
260 
261## Translation System
262 
263### Automated Translation
264 
265- Uses GitHub Actions with co-op-translator workflow
266- Translates to 50+ languages automatically
267- Source files in main directories
268- Translated files in `translations/{language-code}/` directories
269 
270### Adding Manual Translation Improvements
271 
2721. Locate file in `translations/{language-code}/`
2732. Make improvements while preserving structure
2743. Ensure code examples remain functional
2754. Test any localized quiz content
276 
277### Translation Metadata
278 
279Translated files include metadata header:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Debugging and Troubleshooting
293 
294### Common Issues
295 
296**Quiz app fails to start**:
297- Check Node.js version (v14+ recommended)
298- Delete `node_modules` and `package-lock.json`, run `npm install` again
299- Check for port conflicts (default: Vite uses port 5173)
300 
301**API server won't start**:
302- Verify Node.js version meets minimum (node >=10)
303- Check if port is already in use
304- Ensure all dependencies installed with `npm install`
305 
306**Browser extension won't load**:
307- Verify manifest.json is properly formatted
308- Check browser console for errors
309- Follow browser-specific extension installation instructions
310 
311**Python chat project issues**:
312- Ensure OpenAI package installed: `pip install openai`
313- Verify GITHUB_TOKEN environment variable is set
314- Check GitHub Models access permissions
315 
316**Docsify not serving docs**:
317- Install docsify-cli globally: `npm install -g docsify-cli`
318- Run from repository root directory
319- Check that `docs/_sidebar.md` exists
320 
321### Development Environment Tips
322 
323- Use VS Code with Live Server extension for HTML projects
324- Install ESLint and Prettier extensions for consistent formatting
325- Use browser DevTools for debugging JavaScript
326- For Vue projects, install Vue DevTools browser extension
327 
328### Performance Considerations
329 
330- Large number of translated files (50+ languages) means full clones are large
331- Use shallow clone if only working on content: `git clone --depth 1`
332- Exclude translations from searches when working on English content
333- Build processes may be slow on first run (npm install, Vite build)
334 
335## Security Considerations
336 
337### Environment Variables
338 
339- API keys should never be committed to repository
340- Use `.env` files (already in `.gitignore`)
341- Document required environment variables in project READMEs
342 
343### Python Projects
344 
345- Use virtual environments: `python -m venv venv`
346- Keep dependencies updated
347- GitHub tokens should have minimal required permissions
348 
349### GitHub Models Access
350 
351- Personal Access Tokens (PAT) required for GitHub Models
352- Tokens should be stored as environment variables
353- Never commit tokens or credentials
354 
355## Additional Notes
356 
357### Target Audience
358 
359- Complete beginners to web development
360- Students and self-learners
361- Teachers using the curriculum in classrooms
362- Content is designed for accessibility and gradual skill building
363 
364### Educational Philosophy
365 
366- Project-based learning approach
367- Frequent knowledge checks (quizzes)
368- Hands-on coding exercises
369- Real-world application examples
370- Focus on fundamentals before frameworks
371 
372### Repository Maintenance
373 
374- Active community of learners and contributors
375- Regular updates to dependencies and content
376- Issues and discussions monitored by maintainers
377- Translation updates automated via GitHub Actions
378 
379### Related Resources
380 
381- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
382- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) recommended for learners
384- Additional courses: Generative AI, Data Science, ML, IoT curricula available
385 
386### Working with Specific Projects
387 
388For detailed instructions on individual projects, refer to the README files in:
389- `quiz-app/README.md` - Vue 3 quiz application
390- `7-bank-project/README.md` - Banking application with authentication
391- `5-browser-extension/README.md` - Browser extension development
392- `6-space-game/README.md` - Canvas-based game development
393- `9-chat-project/README.md` - AI chat assistant project
394 
395### Monorepo Structure
396 
397While not a traditional monorepo, this repository contains multiple independent projects:
398- Each lesson is self-contained
399- Projects don't share dependencies
400- Work on individual projects without affecting others
401- Clone entire repo for the full curriculum experience
402