AGENTS.md

1# AGENTS.md
2 
3## Project Overview
4 
5Dis na wan educational curriculum repository wey dem dey use teach web development fundamentals to beginners. Di curriculum na big 12-week course wey Microsoft Cloud Advocates make, get 24 hands-on lessons covering JavaScript, CSS, and HTML.
6 
7### Key Components
8 
9- **Educational Content**: 24 structured lessons wey dem organize inside 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 wey get 3 questions each (pre/post-lesson assessments)
12- **Multi-language Support**: Automated translations for 50+ languages through 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 wey get lesson-based structure
18- Every lesson folder get README, code examples, and solutions
19- Standalone projects dey for separate directories (quiz-app, various lesson projects)
20- Translation system dey use GitHub Actions (co-op-translator)
21- Documentation dey serve through Docsify and e dey available as PDF
22 
23## Setup Commands
24 
25Dis repository na mainly for educational content consumption. For to work 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 di 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 wit Prettier
52```
53 
54### Browser Extension Projects
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Follow di 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 for 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 di repository** go your GitHub account
842. **Clone your fork** for your machine
853. **Create new branch** for your changes
864. Make changes for lesson content or code examples
875. Test any code changes inside the relevant project directories
886. Submit pull requests based on contribution guidelines
89 
90### For Learners
91 
921. Fork or clone di repository
932. Go through lesson directories one by one
943. Read README files for each lesson
954. Do pre-lesson quizzes at https://ff-quizzes.netlify.app/web/
965. Work through code examples inside lesson folders
976. Finish assignments and challenges
987. Do post-lesson quizzes
99 
100### Live Development
101 
102- **Documentation**: Run `docsify serve` for root (port 3000)
103- **Quiz App**: Run `npm run dev` inside quiz-app directory
104- **Projects**: Use VS Code Live Server extension for HTML projects
105- **API Projects**: Run `npm start` for the API directories
106 
107## Testing Instructions
108 
109### Quiz App Testing
110 
111```bash
112cd quiz-app
113npm run lint       # Check for code style wahala
114npm run build      # Make sure build dey successful
115```
116 
117### Bank API Testing
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Check for code style wahala
122node server.js     # Make sure say server fit start without any kasala
123```
124 
125### General Testing Approach
126 
127- Dis na educational repository wey no get full automatic tests
128- Manual testing dey focus on:
129  - Code examples dey run without wahala
130  - Links for documentation dey work well
131  - Project build dey complete successful
132  - Examples follow best practices
133 
134### Pre-submission Checks
135 
136- Run `npm run lint` for directories wey get package.json
137- Check say markdown links dey valid
138- Test code examples for browser or Node.js
139- Confirm say translations keep correct structure
140 
141## Code Style Guidelines
142 
143### JavaScript
144 
145- Use modern ES6+ syntax
146- Follow standard ESLint config wey projects get
147- Use meaningful variable and function names for educational clarity
148- Add comments wey explain concepts for learners
149- Format using Prettier if e dey setup
150 
151### HTML/CSS
152 
153- Use semantic HTML5 elements
154- Responsive design principles
155- Clear class naming conventions
156- Comments wey dey explain CSS techniques for learners
157 
158### Python
159 
160- PEP 8 style guidelines
161- Clear, educational code examples
162- Type hints where e go help learning
163 
164### Markdown Documentation
165 
166- Clear heading hierarchy
167- Code blocks with language specification
168- Links to extra resources
169- Screenshots and images inside `images/` directories
170- Alt text for images to support accessibility
171 
172### File Organization
173 
174- Lessons dey numbered one by one (1-getting-started-lessons, 2-js-basics, etc.)
175- Every project get `solution/` and sometimes `start/` or `your-work/` directories
176- Images for lesson-specific `images/` folders
177- Translations dey inside `translations/{language-code}/` structure
178 
179## Build and Deployment
180 
181### Quiz App Deployment (Azure Static Web Apps)
182 
183The quiz-app dey configured for Azure Static Web Apps deployment:
184 
185```bash
186cd quiz-app
187npm run build      # Dey create dist/ folder
188# Dey put for ground wit GitHub Actions workflow wen dem push for 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               # Make PDF from docs
201```
202 
203### Docsify Documentation
204 
205```bash
206npm install -g docsify-cli    # Install Docsify all over di system
207docsify serve                 # Run for localhost:3000
208```
209 
210### Project-specific Builds
211 
212Every project directory fit get their own build process:
213- Vue projects: `npm run build` dey create production bundles
214- Static projects: No build step, just serve files directly
215 
216## Pull Request Guidelines
217 
218### Title Format
219 
220Use clear, descriptive titles wey show wetin change be:
221- `[Quiz-app] Add new quiz for lesson X`
222- `[Lesson-3] Fix typo for terrarium project`
223- `[Translation] Add Spanish translation for lesson 5`
224- `[Docs] Update setup instructions`
225 
226### Required Checks
227 
228Before you submit PR:
229 
2301. **Code Quality**:
231   - Run `npm run lint` for the project directories wey e concern
232   - Fix all lint errors and warnings
233 
2342. **Build Verification**:
235   - Run `npm run build` if e necessary
236   - Make sure no build errors
237 
2383. **Link Validation**:
239   - Test all markdown links
240   - Confirm image refs work
241 
2424. **Content Review**:
243   - Proofread for spelling and grammar
244   - Ensure code examples correct and educational
245   - Confirm translations keep original meaning
246 
247### Contribution Requirements
248 
249- Agree to Microsoft CLA (automatic check for first PR)
250- Follow [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- See [CONTRIBUTING.md](./CONTRIBUTING.md) for details
252- Reference issue numbers for PR description if e get
253 
254### Review Process
255 
256- PRs go through maintainer and community review
257- Educational clarity dey important
258- Code examples suppose follow current best practices
259- Translations go through accuracy and cultural appropriateness check
260 
261## Translation System
262 
263### Automated Translation
264 
265- Dey use GitHub Actions with co-op-translator workflow
266- Translates to 50+ languages automatically
267- Source files dey main directories
268- Translated files dey inside `translations/{language-code}/`
269 
270### Adding Manual Translation Improvements
271 
2721. Find file for `translations/{language-code}/`
2732. Make improvements but keep structure intact
2743. Make sure code examples still dey run well
2754. Test any quiz content wey localized
276 
277### Translation Metadata
278 
279Translated files get 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 no fit start**:
297- Check Node.js version (v14+ recommended)
298- Delete `node_modules` and `package-lock.json`, run `npm install` again
299- Check for port wahala (default: Vite dey use port 5173)
300 
301**API server no go start**:
302- Confirm Node.js version dey at least (node >=10)
303- Check if port don already dey use
304- Make sure all dependencies install with `npm install`
305 
306**Browser extension no go load**:
307- Confirm manifest.json format correct
308- Check browser console for errors
309- Follow browser extension installation instructions
310 
311**Python chat project wahala**:
312- Confirm OpenAI package install: `pip install openai`
313- Confirm GITHUB_TOKEN environment variable set
314- Check GitHub Models permission
315 
316**Docsify no dey serve docs**:
317- Install docsify-cli globally: `npm install -g docsify-cli`
318- Run am from root directory
319- Check say `docs/_sidebar.md` dey
320 
321### Development Environment Tips
322 
323- Use VS Code with Live Server extension for HTML projects
324- Install ESLint and Prettier extensions for proper formatting
325- Use browser DevTools for JavaScript debugging
326- For Vue projects, install Vue DevTools browser extension
327 
328### Performance Considerations
329 
330- Plenty translated files (50+ languages) mean big clones
331- Use shallow clone if na content only: `git clone --depth 1`
332- Exclude translations from searches if you dey focus on English
333- Build steps fit slow for first time (npm install, Vite build)
334 
335## Security Considerations
336 
337### Environment Variables
338 
339- API keys no suppose commit to repository
340- Use `.env` files (already for `.gitignore`)
341- Document needed environment variables inside project READMEs
342 
343### Python Projects
344 
345- Use virtual environments: `python -m venv venv`
346- Keep dependencies updated
347- GitHub tokens need minimal permissions
348 
349### GitHub Models Access
350 
351- Personal Access Tokens (PAT) required for GitHub Models
352- Tokens suppose dey 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 wey use the curriculum for classroom
362- Content dey designed for accessibility and gradual skill building
363 
364### Educational Philosophy
365 
366- Project-based learning style
367- Frequent knowledge checks (quizzes)
368- Hands-on coding exercises
369- Real-life application examples
370- Focus on fundamentals before frameworks
371 
372### Repository Maintenance
373 
374- Active learner and contributor community
375- Regular updates to content and dependencies
376- Maintainers dey monitor issues and discussions
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) dey recommended for learners
384- Other courses: Generative AI, Data Science, ML, IoT curricula dey available
385 
386### Working with Specific Projects
387 
388For detailed instructions on individual projects, check README files for:
389- `quiz-app/README.md` - Vue 3 quiz application
390- `7-bank-project/README.md` - Banking app 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 
397Even though dis no be traditional monorepo, dis repository get many independent projects:
398- Every lesson dey self-contained
399- Projects no dey share dependencies
400- You fit work on individual projects without affect others
401- Clone whole repo for full curriculum experience
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Disclaimer**:  
407Dis dokument don translate wit AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even tho we dey try make am correct, abeg sabi say automated translations fit get errors or mistakes. Di original dokument for im own language na di correct source. For important information, better human translation na di best. We no get fault if any misunderstanding or wrong understanding happen because of dis translation.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->