Phase 3.1: Create learn/ folder template
- Add comprehensive 5-file template structure - 00-OVERVIEW.md: Project intro, quick start, prerequisites - 01-CONCEPTS.md: Security concepts with real world examples - 02-ARCHITECTURE.md: System design and technical decisions - 03-IMPLEMENTATION.md: Code walkthrough with actual examples - 04-CHALLENGES.md: Extension ideas from easy to expert - README.md: Template usage guide and writing guidelines - CHECKLIST.md: Quick reference for filling templates Writing guidelines emphasize: - Human voice (avoiding AI patterns like em dashes, contrast flips) - Concrete examples over abstractions - Real code references with file:line numbers - Real world incidents and vulnerabilities - Practical, actionable content
This commit is contained in:
CarterPerez-dev
parent
6dd4a15ee2
commit
e48e6ebda3
|
|
@ -0,0 +1,101 @@
|
|||
# [Project Name]
|
||||
|
||||
## What This Is
|
||||
|
||||
[2-3 sentence description of what the project does. Be specific about functionality, not buzzwords.]
|
||||
|
||||
## Why This Matters
|
||||
|
||||
[Explain the real world problem this solves. Reference actual incidents, common vulnerabilities, or industry pain points. No fluff about "the evolving threat landscape" - get concrete.]
|
||||
|
||||
**Real world scenarios where this applies:**
|
||||
- [Specific scenario 1]
|
||||
- [Specific scenario 2]
|
||||
- [Specific scenario 3]
|
||||
|
||||
## What You'll Learn
|
||||
|
||||
This project teaches you how [core concept] works under the hood. By building it yourself, you'll understand:
|
||||
|
||||
**Security Concepts:**
|
||||
- [Concept 1 - explain what it is, not just list it]
|
||||
- [Concept 2]
|
||||
- [Concept 3]
|
||||
|
||||
**Technical Skills:**
|
||||
- [Skill 1 - be specific about what aspect you'll actually implement]
|
||||
- [Skill 2]
|
||||
- [Skill 3]
|
||||
|
||||
**Tools and Techniques:**
|
||||
- [Tool/technique 1 - explain how it's used in the project]
|
||||
- [Tool/technique 2]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before starting, you should understand:
|
||||
|
||||
**Required knowledge:**
|
||||
- [Prerequisite 1 with specific examples of what you need to know]
|
||||
- [Prerequisite 2]
|
||||
- [Prerequisite 3]
|
||||
|
||||
**Tools you'll need:**
|
||||
- [Tool 1] - [brief explanation of why]
|
||||
- [Tool 2]
|
||||
- [Tool 3]
|
||||
|
||||
**Helpful but not required:**
|
||||
- [Nice to have 1]
|
||||
- [Nice to have 2]
|
||||
|
||||
## Quick Start
|
||||
|
||||
Get the project running locally:
|
||||
|
||||
```bash
|
||||
# Clone and navigate
|
||||
cd PROJECTS/[difficulty]/[project-name]
|
||||
|
||||
# [Installation steps specific to the project]
|
||||
# Keep this minimal - just enough to see it work
|
||||
|
||||
# Run the project
|
||||
[command to start]
|
||||
```
|
||||
|
||||
Expected output: [describe what success looks like]
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
[project-name]/
|
||||
├── [key directory 1]/ # [what this contains]
|
||||
├── [key directory 2]/ # [what this contains]
|
||||
├── [key file 1] # [what this does]
|
||||
└── [key file 2] # [what this does]
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Understand the concepts** - Read [01-CONCEPTS.md](./01-CONCEPTS.md) to learn the security fundamentals
|
||||
2. **Study the architecture** - Read [02-ARCHITECTURE.md](./02-ARCHITECTURE.md) to see how it's designed
|
||||
3. **Walk through the code** - Read [03-IMPLEMENTATION.md](./03-IMPLEMENTATION.md) for implementation details
|
||||
4. **Extend the project** - Read [04-CHALLENGES.md](./04-CHALLENGES.md) for ideas to build on
|
||||
|
||||
## Common Issues
|
||||
|
||||
**[Common problem 1]**
|
||||
```
|
||||
[Error message or symptom]
|
||||
```
|
||||
Solution: [How to fix it]
|
||||
|
||||
**[Common problem 2]**
|
||||
Solution: [How to fix it]
|
||||
|
||||
## Related Projects
|
||||
|
||||
If you found this interesting, check out:
|
||||
- [Related project 1] - [why it's related]
|
||||
- [Related project 2] - [why it's related]
|
||||
|
|
@ -0,0 +1,139 @@
|
|||
# Core Security Concepts
|
||||
|
||||
This document explains the security concepts you'll encounter while building this project. These are not just definitions - we'll dig into why they matter and how they actually work.
|
||||
|
||||
## [Primary Concept]
|
||||
|
||||
### What It Is
|
||||
|
||||
[Explain the concept in plain language. No jargon without explanation. Assume the reader is smart but unfamiliar.]
|
||||
|
||||
### Why It Matters
|
||||
|
||||
[Explain the real world impact. What goes wrong without it? Reference actual breaches or incidents if relevant.]
|
||||
|
||||
### How It Works
|
||||
|
||||
[Break down the technical mechanism. Use examples and code snippets where helpful. ASCII diagrams are good.]
|
||||
|
||||
```
|
||||
[Diagram or code example showing the concept in action]
|
||||
```
|
||||
|
||||
### Common Attacks
|
||||
|
||||
[List specific attack techniques that exploit this. Be concrete about what an attacker does.]
|
||||
|
||||
1. **[Attack 1]** - [How it works, what the attacker gains]
|
||||
2. **[Attack 2]** - [How it works, what the attacker gains]
|
||||
3. **[Attack 3]** - [How it works, what the attacker gains]
|
||||
|
||||
### Defense Strategies
|
||||
|
||||
[Explain how to protect against these attacks. Connect back to what this project implements.]
|
||||
|
||||
## [Secondary Concept]
|
||||
|
||||
### What It Is
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
### Why It Matters
|
||||
|
||||
[Real world impact]
|
||||
|
||||
### How It Works
|
||||
|
||||
[Technical mechanism]
|
||||
|
||||
### Common Pitfalls
|
||||
|
||||
[Where developers get this wrong. Based on actual mistakes you see in production code.]
|
||||
|
||||
**Mistake 1: [Common error]**
|
||||
```[language]
|
||||
# Bad
|
||||
[code showing the mistake]
|
||||
|
||||
# Good
|
||||
[code showing the correct approach]
|
||||
```
|
||||
|
||||
**Mistake 2: [Another common error]**
|
||||
[Explanation of why this is wrong]
|
||||
|
||||
## [Additional Concept]
|
||||
|
||||
[Follow same pattern for each major concept]
|
||||
|
||||
## How These Concepts Relate
|
||||
|
||||
[Show how the concepts connect to each other. Security is a system, not isolated techniques.]
|
||||
|
||||
```
|
||||
[Concept 1]
|
||||
↓
|
||||
affects
|
||||
↓
|
||||
[Concept 2]
|
||||
↓
|
||||
requires
|
||||
↓
|
||||
[Concept 3]
|
||||
```
|
||||
|
||||
## Industry Standards and Frameworks
|
||||
|
||||
### OWASP Top 10
|
||||
|
||||
This project addresses:
|
||||
- **[OWASP Category]** - [Specific vulnerability and how this project handles it]
|
||||
- **[Another category]** - [How this project relates]
|
||||
|
||||
### MITRE ATT&CK
|
||||
|
||||
Relevant techniques:
|
||||
- **[Technique ID]** - [Technique name] - [How this project detects or prevents it]
|
||||
- **[Another technique]** - [Connection to the project]
|
||||
|
||||
### CWE
|
||||
|
||||
Common weakness enumerations covered:
|
||||
- **[CWE-XXX]** - [Weakness name] - [How this project demonstrates or prevents it]
|
||||
|
||||
## Real World Examples
|
||||
|
||||
### Case Study 1: [Actual Incident]
|
||||
|
||||
[Describe a real breach or vulnerability that relates to these concepts. Include:
|
||||
- What happened
|
||||
- How the attack worked
|
||||
- What defenses failed
|
||||
- How this could have been prevented]
|
||||
|
||||
### Case Study 2: [Another Example]
|
||||
|
||||
[Another real world example]
|
||||
|
||||
## Testing Your Understanding
|
||||
|
||||
Before moving to the architecture, make sure you can answer:
|
||||
|
||||
1. [Question that tests understanding of concept 1]
|
||||
2. [Question that requires applying concept 2]
|
||||
3. [Question that connects multiple concepts]
|
||||
|
||||
If these questions feel unclear, re-read the relevant sections. The implementation will make more sense once these fundamentals click.
|
||||
|
||||
## Further Reading
|
||||
|
||||
**Essential:**
|
||||
- [Resource 1] - [Why this is valuable]
|
||||
- [Resource 2] - [What you'll get from it]
|
||||
|
||||
**Deep dives:**
|
||||
- [Advanced resource 1] - [When to read this]
|
||||
- [Advanced resource 2] - [What this covers that we didn't]
|
||||
|
||||
**Historical context:**
|
||||
- [Paper or talk] - [Why this matters for understanding the evolution]
|
||||
|
|
@ -0,0 +1,370 @@
|
|||
# System Architecture
|
||||
|
||||
This document breaks down how the system is designed and why certain architectural decisions were made.
|
||||
|
||||
## High Level Architecture
|
||||
|
||||
```
|
||||
[ASCII diagram showing major components and how they connect]
|
||||
|
||||
Example:
|
||||
┌─────────────┐
|
||||
│ Client │
|
||||
└──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ Component │
|
||||
└──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ Storage │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
### Component Breakdown
|
||||
|
||||
**[Component 1]**
|
||||
- Purpose: [What this component does]
|
||||
- Responsibilities: [Specific tasks it handles]
|
||||
- Interfaces: [How other components interact with it]
|
||||
|
||||
**[Component 2]**
|
||||
- Purpose: [What this component does]
|
||||
- Responsibilities: [Specific tasks it handles]
|
||||
- Interfaces: [How other components interact with it]
|
||||
|
||||
**[Component 3]**
|
||||
- Purpose: [What this component does]
|
||||
- Responsibilities: [Specific tasks it handles]
|
||||
- Interfaces: [How other components interact with it]
|
||||
|
||||
## Data Flow
|
||||
|
||||
### [Primary Use Case Flow]
|
||||
|
||||
Step by step walkthrough of what happens when [primary operation]:
|
||||
|
||||
```
|
||||
1. [Action] → [Component]
|
||||
[What happens, what data is passed]
|
||||
|
||||
2. [Component] → [Next component]
|
||||
[Processing that occurs, transformations]
|
||||
|
||||
3. [Next component] → [Result]
|
||||
[Final output or state change]
|
||||
```
|
||||
|
||||
Example with code references:
|
||||
```
|
||||
1. User sends request → API endpoint (src/routes/endpoint.py:42)
|
||||
Validates input, extracts credentials
|
||||
|
||||
2. API → Service layer (src/services/auth.py:108)
|
||||
Business logic runs, queries database
|
||||
|
||||
3. Service → Response (src/routes/endpoint.py:67)
|
||||
Formats result, returns to user
|
||||
```
|
||||
|
||||
### [Secondary Use Case Flow]
|
||||
|
||||
[Repeat for other major operations]
|
||||
|
||||
## Design Patterns
|
||||
|
||||
### [Pattern 1 Used in Project]
|
||||
|
||||
**What it is:**
|
||||
[Brief explanation of the pattern]
|
||||
|
||||
**Where we use it:**
|
||||
[Specific files or components that implement this pattern]
|
||||
|
||||
**Why we chose it:**
|
||||
[Advantages for this specific use case, alternatives considered]
|
||||
|
||||
**Trade-offs:**
|
||||
- Pros: [What you gain]
|
||||
- Cons: [What you give up]
|
||||
|
||||
Example implementation:
|
||||
```[language]
|
||||
[Code snippet showing the pattern in action from the actual project]
|
||||
```
|
||||
|
||||
### [Pattern 2]
|
||||
|
||||
[Same structure]
|
||||
|
||||
## Layer Separation
|
||||
|
||||
[If applicable - explain the layer architecture]
|
||||
|
||||
```
|
||||
┌────────────────────────────────────┐
|
||||
│ Layer 1: [Name] │
|
||||
│ - [Responsibility] │
|
||||
│ - [What it doesn't do] │
|
||||
└────────────────────────────────────┘
|
||||
↓
|
||||
┌────────────────────────────────────┐
|
||||
│ Layer 2: [Name] │
|
||||
│ - [Responsibility] │
|
||||
│ - [What it doesn't do] │
|
||||
└────────────────────────────────────┘
|
||||
↓
|
||||
┌────────────────────────────────────┐
|
||||
│ Layer 3: [Name] │
|
||||
│ - [Responsibility] │
|
||||
│ - [What it doesn't do] │
|
||||
└────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Why Layers?
|
||||
|
||||
[Explain the benefits of this separation]
|
||||
- [Benefit 1]
|
||||
- [Benefit 2]
|
||||
- [Benefit 3]
|
||||
|
||||
### What Lives Where
|
||||
|
||||
**[Layer 1]:**
|
||||
- Files: [Which files belong to this layer]
|
||||
- Imports: [Can import from which other layers]
|
||||
- Forbidden: [What this layer should never do]
|
||||
|
||||
**[Layer 2]:**
|
||||
[Same structure]
|
||||
|
||||
**[Layer 3]:**
|
||||
[Same structure]
|
||||
|
||||
## Data Models
|
||||
|
||||
### [Model 1]
|
||||
|
||||
```[language]
|
||||
[Actual data structure from the project]
|
||||
```
|
||||
|
||||
**Fields explained:**
|
||||
- `[field_name]`: [What this stores, why it's needed, any constraints]
|
||||
- `[field_name]`: [Explanation]
|
||||
- `[field_name]`: [Explanation]
|
||||
|
||||
**Relationships:**
|
||||
- [How this model connects to others]
|
||||
- [Why these relationships exist]
|
||||
|
||||
### [Model 2]
|
||||
|
||||
[Same structure for each major data model]
|
||||
|
||||
## Security Architecture
|
||||
|
||||
### Threat Model
|
||||
|
||||
What we're protecting against:
|
||||
1. **[Threat 1]** - [Specific attack scenario]
|
||||
2. **[Threat 2]** - [Specific attack scenario]
|
||||
3. **[Threat 3]** - [Specific attack scenario]
|
||||
|
||||
What we're NOT protecting against (out of scope):
|
||||
- [Thing 1] - [Why this is out of scope]
|
||||
- [Thing 2] - [Reason]
|
||||
|
||||
### Defense Layers
|
||||
|
||||
[Explain how security is implemented at different levels]
|
||||
|
||||
```
|
||||
Layer 1: [Defense mechanism]
|
||||
↓
|
||||
Layer 2: [Defense mechanism]
|
||||
↓
|
||||
Layer 3: [Defense mechanism]
|
||||
```
|
||||
|
||||
**Why multiple layers?**
|
||||
[Explain defense in depth for this specific project]
|
||||
|
||||
## Storage Strategy
|
||||
|
||||
### [Storage Type 1]
|
||||
|
||||
**What we store:**
|
||||
- [Data type 1]
|
||||
- [Data type 2]
|
||||
|
||||
**Why this storage:**
|
||||
[Explain choice - performance, durability, cost, etc]
|
||||
|
||||
**Schema design:**
|
||||
```
|
||||
[Show key structure or table design]
|
||||
```
|
||||
|
||||
### [Storage Type 2]
|
||||
|
||||
[If using multiple storage backends]
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
[VARIABLE_NAME] # [What it configures, default value, why you'd change it]
|
||||
[VARIABLE_NAME] # [Explanation]
|
||||
```
|
||||
|
||||
### Configuration Strategy
|
||||
|
||||
[Explain how config is managed - files, env vars, secrets, etc]
|
||||
|
||||
**Development:**
|
||||
[How config works in dev]
|
||||
|
||||
**Production:**
|
||||
[How config works in prod, security considerations]
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Bottlenecks
|
||||
|
||||
Where this system gets slow under load:
|
||||
1. **[Bottleneck 1]** - [Why this happens, when it matters]
|
||||
2. **[Bottleneck 2]** - [Explanation]
|
||||
|
||||
### Optimizations
|
||||
|
||||
What we did to make it faster:
|
||||
- **[Optimization 1]**: [What we changed, impact it had]
|
||||
- **[Optimization 2]**: [Details]
|
||||
|
||||
### Scalability
|
||||
|
||||
**Vertical scaling:**
|
||||
[How to scale up - more CPU/RAM]
|
||||
[Where limits are]
|
||||
|
||||
**Horizontal scaling:**
|
||||
[How to scale out - more instances]
|
||||
[What needs to change to support this]
|
||||
|
||||
## Design Decisions
|
||||
|
||||
### [Major Decision 1]
|
||||
|
||||
**What we chose:**
|
||||
[The approach taken]
|
||||
|
||||
**Alternatives considered:**
|
||||
- [Option A] - Rejected because [reason]
|
||||
- [Option B] - Rejected because [reason]
|
||||
|
||||
**Trade-offs:**
|
||||
[What we gained and what we gave up with this choice]
|
||||
|
||||
### [Major Decision 2]
|
||||
|
||||
[Same structure for each significant architectural choice]
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
[If applicable - how this runs in production]
|
||||
|
||||
```
|
||||
[Diagram showing deployment topology]
|
||||
```
|
||||
|
||||
**Components:**
|
||||
- [Service 1]: [What it runs, how many instances, why]
|
||||
- [Service 2]: [Details]
|
||||
|
||||
**Infrastructure:**
|
||||
- [Database/cache/etc]: [How it's deployed]
|
||||
|
||||
## Error Handling Strategy
|
||||
|
||||
### Error Types
|
||||
|
||||
1. **[Error category 1]** - [What causes this, how we handle it]
|
||||
2. **[Error category 2]** - [Details]
|
||||
|
||||
### Recovery Mechanisms
|
||||
|
||||
[How the system recovers from failures]
|
||||
|
||||
**[Failure scenario 1]:**
|
||||
- Detection: [How we know it happened]
|
||||
- Response: [What the system does]
|
||||
- Recovery: [How to get back to normal]
|
||||
|
||||
## Extensibility
|
||||
|
||||
### Where to Add Features
|
||||
|
||||
Want to add [type of feature]? Here's where it goes:
|
||||
|
||||
1. [Step 1 with file references]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
### Plugin Architecture
|
||||
|
||||
[If applicable - how the system can be extended without modifying core code]
|
||||
|
||||
## Limitations
|
||||
|
||||
Current architectural limitations:
|
||||
1. **[Limitation 1]** - [What you can't do, why not, how to fix it]
|
||||
2. **[Limitation 2]** - [Details]
|
||||
|
||||
These are not bugs, they're conscious trade-offs. Fixing them would require [what changes].
|
||||
|
||||
## Comparison to Similar Systems
|
||||
|
||||
### [Similar tool/approach 1]
|
||||
|
||||
How we're different:
|
||||
- [Difference 1]
|
||||
- [Difference 2]
|
||||
|
||||
Why we made different choices:
|
||||
[Reasoning specific to this use case]
|
||||
|
||||
### [Similar tool/approach 2]
|
||||
|
||||
[Same structure]
|
||||
|
||||
## Evolution
|
||||
|
||||
### Version 1.0 Design
|
||||
|
||||
[If relevant - how the architecture has changed]
|
||||
|
||||
Initial design was [approach]. We changed to current design because [reason].
|
||||
|
||||
### Future Improvements
|
||||
|
||||
Planned architectural changes:
|
||||
1. **[Improvement 1]** - [Why we want this, what it enables]
|
||||
2. **[Improvement 2]** - [Details]
|
||||
|
||||
## Key Files Reference
|
||||
|
||||
Quick map of where to find things:
|
||||
|
||||
- `[file/directory]` - [What's implemented here]
|
||||
- `[file/directory]` - [Purpose]
|
||||
- `[file/directory]` - [What to look at]
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you understand the architecture:
|
||||
1. Read [03-IMPLEMENTATION.md](./03-IMPLEMENTATION.md) for code walkthrough
|
||||
2. Try modifying [specific component] to understand [concept]
|
||||
|
|
@ -0,0 +1,545 @@
|
|||
# Implementation Guide
|
||||
|
||||
This document walks through the actual code. We'll build key features step by step and explain the decisions along the way.
|
||||
|
||||
## File Structure Walkthrough
|
||||
|
||||
```
|
||||
[project-name]/
|
||||
├── [directory]/
|
||||
│ ├── [file1] # [What this implements]
|
||||
│ └── [file2] # [What this implements]
|
||||
├── [directory]/
|
||||
│ └── [file] # [What this implements]
|
||||
└── [key file] # [What this implements]
|
||||
```
|
||||
|
||||
## Building [Core Feature 1]
|
||||
|
||||
### Step 1: [First Step]
|
||||
|
||||
What we're building: [Specific functionality]
|
||||
|
||||
Create `[filename]`:
|
||||
|
||||
```[language]
|
||||
[Code with inline comments explaining the important parts]
|
||||
```
|
||||
|
||||
**Why this code works:**
|
||||
- [Line/section 1]: [Explanation of what it does and why]
|
||||
- [Line/section 2]: [Explanation]
|
||||
- [Line/section 3]: [Explanation]
|
||||
|
||||
**Common mistakes here:**
|
||||
```[language]
|
||||
# Wrong approach
|
||||
[Code showing what NOT to do]
|
||||
|
||||
# Why this fails: [Explanation of the problem]
|
||||
```
|
||||
|
||||
### Step 2: [Second Step]
|
||||
|
||||
Now we need to [next functionality].
|
||||
|
||||
In `[filename]` (lines XX-YY):
|
||||
|
||||
```[language]
|
||||
[Relevant code snippet from the actual project]
|
||||
```
|
||||
|
||||
**What's happening:**
|
||||
1. [Step by step breakdown]
|
||||
2. [Explanation]
|
||||
3. [Explanation]
|
||||
|
||||
**Why we do it this way:**
|
||||
[Explain the reasoning - performance, security, maintainability, etc]
|
||||
|
||||
**Alternative approaches:**
|
||||
- [Approach A]: Works but [drawback]
|
||||
- [Approach B]: Simpler but [limitation]
|
||||
|
||||
### Step 3: [Third Step]
|
||||
|
||||
[Continue pattern for each major step]
|
||||
|
||||
## Building [Core Feature 2]
|
||||
|
||||
### The Problem
|
||||
|
||||
[Describe what challenge this feature solves]
|
||||
|
||||
### The Solution
|
||||
|
||||
[High level approach before diving into code]
|
||||
|
||||
### Implementation
|
||||
|
||||
In `[filename]`:
|
||||
|
||||
```[language]
|
||||
[Code implementation]
|
||||
```
|
||||
|
||||
**Key parts explained:**
|
||||
|
||||
**[Function/class name]** (`[filename]:[line]`)
|
||||
```[language]
|
||||
[Focused code snippet]
|
||||
```
|
||||
This handles [specific responsibility]. The reason we [design choice] is because [explanation].
|
||||
|
||||
**[Another function/class]** (`[filename]:[line]`)
|
||||
```[language]
|
||||
[Code snippet]
|
||||
```
|
||||
[Explanation of what this does differently and why]
|
||||
|
||||
### Testing This Feature
|
||||
|
||||
```[language]
|
||||
[Test code or example usage]
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
[What you should see]
|
||||
```
|
||||
|
||||
If you see [error], it means [problem and fix].
|
||||
|
||||
## Security Implementation
|
||||
|
||||
### [Security Feature 1]
|
||||
|
||||
File: `[filename]`
|
||||
|
||||
```[language]
|
||||
[Security related code]
|
||||
```
|
||||
|
||||
**What this prevents:**
|
||||
[Specific attack or vulnerability]
|
||||
|
||||
**How it works:**
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
**What happens if you remove this:**
|
||||
[Demonstrate why this security measure is necessary]
|
||||
|
||||
### [Security Feature 2]
|
||||
|
||||
[Same pattern for each security mechanism]
|
||||
|
||||
## Data Flow Example
|
||||
|
||||
Let's trace a complete request through the system.
|
||||
|
||||
**Scenario:** [Specific user action]
|
||||
|
||||
### Request Comes In
|
||||
|
||||
```[language]
|
||||
# Entry point: [filename]:[line]
|
||||
[Code at entry point]
|
||||
```
|
||||
|
||||
At this point:
|
||||
- [State/data description]
|
||||
- [What's been validated]
|
||||
- [What happens next]
|
||||
|
||||
### Processing Layer
|
||||
|
||||
```[language]
|
||||
# Processing: [filename]:[line]
|
||||
[Code in processing layer]
|
||||
```
|
||||
|
||||
This code:
|
||||
- [Action 1]
|
||||
- [Action 2]
|
||||
- [Why it's structured this way]
|
||||
|
||||
### Storage/Output
|
||||
|
||||
```[language]
|
||||
# Final step: [filename]:[line]
|
||||
[Code that completes the operation]
|
||||
```
|
||||
|
||||
The result is [outcome]. We store/return it as [format] because [reason].
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
### [Error Type 1]
|
||||
|
||||
When [condition] happens, we need to [response].
|
||||
|
||||
```[language]
|
||||
# [filename]:[line]
|
||||
try:
|
||||
[operation that might fail]
|
||||
except [SpecificException] as e:
|
||||
[error handling]
|
||||
```
|
||||
|
||||
**Why this specific handling:**
|
||||
[Explanation of the error handling strategy]
|
||||
|
||||
**What NOT to do:**
|
||||
```[language]
|
||||
# Bad: catching everything
|
||||
try:
|
||||
[operation]
|
||||
except Exception:
|
||||
pass # Silently fails - terrible idea
|
||||
```
|
||||
|
||||
This hides actual problems. Always handle specific exceptions.
|
||||
|
||||
### [Error Type 2]
|
||||
|
||||
[Continue for major error cases]
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
### [Optimization 1]
|
||||
|
||||
**Before:**
|
||||
```[language]
|
||||
[Slow/naive implementation]
|
||||
```
|
||||
|
||||
This was slow because [reason]. With [example scenario], it took [time/resources].
|
||||
|
||||
**After:**
|
||||
```[language]
|
||||
[Optimized implementation]
|
||||
```
|
||||
|
||||
**What changed:**
|
||||
- [Change 1]: [Impact]
|
||||
- [Change 2]: [Impact]
|
||||
|
||||
**Benchmarks:**
|
||||
- Before: [metric]
|
||||
- After: [metric]
|
||||
- Improvement: [percentage/factor]
|
||||
|
||||
### [Optimization 2]
|
||||
|
||||
[Same pattern]
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### Loading Config
|
||||
|
||||
```[language]
|
||||
# [filename]:[line]
|
||||
[Config loading code]
|
||||
```
|
||||
|
||||
**Why this approach:**
|
||||
[Explain the config strategy]
|
||||
|
||||
**Validation:**
|
||||
```[language]
|
||||
[Config validation code if applicable]
|
||||
```
|
||||
|
||||
We validate early because [reason]. If config is wrong, we want to fail fast at startup, not mysteriously later.
|
||||
|
||||
## Database/Storage Operations
|
||||
|
||||
### [Operation Type 1]
|
||||
|
||||
```[language]
|
||||
# [filename]:[line]
|
||||
[Database operation code]
|
||||
```
|
||||
|
||||
**Important details:**
|
||||
- [Transaction handling]: [Why it matters]
|
||||
- [Connection management]: [How we avoid leaks]
|
||||
- [Query optimization]: [Why we wrote it this way]
|
||||
|
||||
### Migrations
|
||||
|
||||
[If applicable]
|
||||
|
||||
When you change [data structure], run:
|
||||
```bash
|
||||
[migration command]
|
||||
```
|
||||
|
||||
This updates [what changes] without losing [what's preserved].
|
||||
|
||||
## Integration Points
|
||||
|
||||
### [External System/API 1]
|
||||
|
||||
How we integrate with [system]:
|
||||
|
||||
```[language]
|
||||
# [filename]:[line]
|
||||
[Integration code]
|
||||
```
|
||||
|
||||
**Authentication:**
|
||||
[How auth is handled]
|
||||
|
||||
**Error handling:**
|
||||
[What happens when external system fails]
|
||||
|
||||
**Rate limiting:**
|
||||
[How we avoid getting throttled]
|
||||
|
||||
### [External System 2]
|
||||
|
||||
[Same pattern]
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
|
||||
Example test for [component]:
|
||||
|
||||
```[language]
|
||||
# tests/[filename]
|
||||
[Test code]
|
||||
```
|
||||
|
||||
**What this tests:**
|
||||
- [Behavior 1]
|
||||
- [Behavior 2]
|
||||
|
||||
**Why these specific assertions:**
|
||||
[Explain what could break and how test catches it]
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```[language]
|
||||
# tests/[filename]
|
||||
[Integration test code]
|
||||
```
|
||||
|
||||
This tests [end-to-end scenario]. We need this because unit tests don't catch [specific integration issues].
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
[test command]
|
||||
```
|
||||
|
||||
If tests fail with [error], check [common cause].
|
||||
|
||||
## Common Implementation Pitfalls
|
||||
|
||||
### Pitfall 1: [Common Mistake]
|
||||
|
||||
**Symptom:**
|
||||
[What the developer sees]
|
||||
|
||||
**Cause:**
|
||||
```[language]
|
||||
# The problematic code
|
||||
[What they probably wrote]
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```[language]
|
||||
# Correct approach
|
||||
[How to do it right]
|
||||
```
|
||||
|
||||
**Why this matters:**
|
||||
[Real impact of the mistake]
|
||||
|
||||
### Pitfall 2: [Another Mistake]
|
||||
|
||||
[Same pattern for common errors you actually see in this domain]
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
### [Issue Type 1]
|
||||
|
||||
**Problem:** [Description]
|
||||
|
||||
**How to debug:**
|
||||
1. Check [location 1] for [evidence]
|
||||
2. Look at [logs/output] for [pattern]
|
||||
3. Verify [assumption]
|
||||
|
||||
**Common causes:**
|
||||
- [Cause 1]
|
||||
- [Cause 2]
|
||||
|
||||
### [Issue Type 2]
|
||||
|
||||
[Continue for common debugging scenarios]
|
||||
|
||||
## Code Organization Principles
|
||||
|
||||
### Why [File/Module] is Structured This Way
|
||||
|
||||
```
|
||||
[module]/
|
||||
├── [file1] # [Responsibility]
|
||||
└── [file2] # [Responsibility]
|
||||
```
|
||||
|
||||
We separate [concern 1] from [concern 2] because:
|
||||
- [Reason 1]
|
||||
- [Reason 2]
|
||||
|
||||
This makes [benefit].
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- `[pattern]` = [What this naming means]
|
||||
- `[pattern]` = [Convention explanation]
|
||||
|
||||
Following these patterns makes it easier to [benefit].
|
||||
|
||||
## Extending the Code
|
||||
|
||||
### Adding a New [Feature Type]
|
||||
|
||||
Want to add [capability]? Here's the process:
|
||||
|
||||
1. **Create [component]** in `[location]`
|
||||
```[language]
|
||||
[Template code to start from]
|
||||
```
|
||||
|
||||
2. **Register [component]** in `[location]`
|
||||
```[language]
|
||||
[Registration code]
|
||||
```
|
||||
|
||||
3. **Add tests** in `[location]`
|
||||
```[language]
|
||||
[Test template]
|
||||
```
|
||||
|
||||
### Plugin Pattern
|
||||
|
||||
[If applicable - how to extend without modifying core]
|
||||
|
||||
Create `plugins/[name].py`:
|
||||
```[language]
|
||||
[Plugin template code]
|
||||
```
|
||||
|
||||
The system discovers plugins by [mechanism]. Your plugin must implement [interface].
|
||||
|
||||
## Code Style and Standards
|
||||
|
||||
### Formatting
|
||||
|
||||
We use [linter/formatter]:
|
||||
```bash
|
||||
[command to run it]
|
||||
```
|
||||
|
||||
Key rules:
|
||||
- [Rule 1]: [Why]
|
||||
- [Rule 2]: [Why]
|
||||
|
||||
### Type Annotations
|
||||
|
||||
[If applicable]
|
||||
|
||||
```[language]
|
||||
# Good
|
||||
[properly typed code]
|
||||
|
||||
# Bad
|
||||
[untyped code]
|
||||
```
|
||||
|
||||
Types catch [specific bugs] at [development stage] instead of [runtime].
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Why Each Dependency
|
||||
|
||||
- **[package1]** ([version]): [What we use it for, why this package specifically]
|
||||
- **[package2]** ([version]): [Purpose and reasoning]
|
||||
- **[package3]** ([version]): [Explanation]
|
||||
|
||||
### Dependency Security
|
||||
|
||||
Check for vulnerabilities:
|
||||
```bash
|
||||
[security scan command]
|
||||
```
|
||||
|
||||
If you see [vulnerability type], [how to handle it].
|
||||
|
||||
## Build and Deploy
|
||||
|
||||
### Building
|
||||
|
||||
```bash
|
||||
[build commands]
|
||||
```
|
||||
|
||||
This produces [artifacts]. The build process:
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Start development environment
|
||||
[dev command]
|
||||
|
||||
# Hot reload is enabled - changes to [files] reload automatically
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
|
||||
[High level deployment process]
|
||||
|
||||
Key differences from dev:
|
||||
- [Difference 1]
|
||||
- [Difference 2]
|
||||
|
||||
## Performance Profiling
|
||||
|
||||
### Finding Bottlenecks
|
||||
|
||||
```bash
|
||||
[profiling command]
|
||||
```
|
||||
|
||||
Look for:
|
||||
- [Metric 1] above [threshold] = [problem]
|
||||
- [Metric 2] indicates [bottleneck]
|
||||
|
||||
### Memory Profiling
|
||||
|
||||
[If relevant]
|
||||
|
||||
```bash
|
||||
[memory profiling command]
|
||||
```
|
||||
|
||||
Common memory leaks in this codebase:
|
||||
- [Pattern 1]: [How to spot and fix]
|
||||
- [Pattern 2]: [Details]
|
||||
|
||||
## Next Steps
|
||||
|
||||
You've seen how the code works. Now:
|
||||
|
||||
1. **Try the challenges** - [04-CHALLENGES.md](./04-CHALLENGES.md) has extension ideas
|
||||
2. **Modify the code** - Change [component] to [variation] to test your understanding
|
||||
3. **Read related projects** - [Link to related project] builds on these concepts
|
||||
|
|
@ -0,0 +1,420 @@
|
|||
# Extension Challenges
|
||||
|
||||
You've built the base project. Now make it yours by extending it with new features.
|
||||
|
||||
These challenges are ordered by difficulty. Start with the easier ones to build confidence, then tackle the harder ones when you want to dive deeper.
|
||||
|
||||
## Easy Challenges
|
||||
|
||||
### Challenge 1: [Extension Idea]
|
||||
|
||||
**What to build:**
|
||||
[Specific feature to add]
|
||||
|
||||
**Why it's useful:**
|
||||
[Real world scenario where this matters]
|
||||
|
||||
**What you'll learn:**
|
||||
- [Skill/concept 1]
|
||||
- [Skill/concept 2]
|
||||
|
||||
**Hints:**
|
||||
- Look at `[filename]` - you'll need to modify [component]
|
||||
- The key is [concept/technique]
|
||||
- Don't forget to handle [edge case]
|
||||
|
||||
**Test it works:**
|
||||
[How to verify the feature works correctly]
|
||||
|
||||
### Challenge 2: [Another Extension]
|
||||
|
||||
[Same format for each challenge]
|
||||
|
||||
### Challenge 3: [Another Extension]
|
||||
|
||||
[Continue pattern]
|
||||
|
||||
## Intermediate Challenges
|
||||
|
||||
### Challenge 4: [More Complex Feature]
|
||||
|
||||
**What to build:**
|
||||
[Feature description]
|
||||
|
||||
**Real world application:**
|
||||
[Where you'd actually use this in production]
|
||||
|
||||
**What you'll learn:**
|
||||
- [New concept 1]
|
||||
- [New concept 2]
|
||||
- [Integration with existing code]
|
||||
|
||||
**Implementation approach:**
|
||||
|
||||
1. **Add [component]** to handle [responsibility]
|
||||
- Files to create: `[filename]`
|
||||
- Files to modify: `[filename]`
|
||||
|
||||
2. **Integrate with [existing system]**
|
||||
- Hook into [entry point]
|
||||
- Pass data through [flow]
|
||||
|
||||
3. **Test edge cases:**
|
||||
- What if [scenario 1]?
|
||||
- How do you handle [scenario 2]?
|
||||
|
||||
**Hints:**
|
||||
- You'll need [technology/library]
|
||||
- The tricky part is [specific challenge]
|
||||
- Consider [design pattern] for [aspect]
|
||||
|
||||
**Extra credit:**
|
||||
[Additional variation to make it more sophisticated]
|
||||
|
||||
### Challenge 5: [Another Intermediate Feature]
|
||||
|
||||
[Continue pattern]
|
||||
|
||||
## Advanced Challenges
|
||||
|
||||
### Challenge 6: [Complex Integration]
|
||||
|
||||
**What to build:**
|
||||
[Significant new capability]
|
||||
|
||||
**Why this is hard:**
|
||||
[What makes this challenging - multiple components, complex state, performance, etc]
|
||||
|
||||
**What you'll learn:**
|
||||
- [Advanced concept 1]
|
||||
- [Advanced concept 2]
|
||||
- [System design skill]
|
||||
|
||||
**Architecture changes needed:**
|
||||
|
||||
```
|
||||
[Diagram showing how the new feature fits in]
|
||||
```
|
||||
|
||||
**Implementation steps:**
|
||||
|
||||
1. **Research phase**
|
||||
- Read about [technology/concept]
|
||||
- Understand [standard/protocol/algorithm]
|
||||
- Look at [reference implementation]
|
||||
|
||||
2. **Design phase**
|
||||
- Decide between [approach A] vs [approach B]
|
||||
- Consider impact on [existing component]
|
||||
- Plan database/storage changes
|
||||
|
||||
3. **Implementation phase**
|
||||
- Start with [minimal version]
|
||||
- Add [capability 1]
|
||||
- Add [capability 2]
|
||||
|
||||
4. **Testing phase**
|
||||
- Unit test [component]
|
||||
- Integration test [flow]
|
||||
- Performance test under [load scenario]
|
||||
|
||||
**Gotchas:**
|
||||
- [Common mistake 1]: [How to avoid]
|
||||
- [Common mistake 2]: [How to avoid]
|
||||
|
||||
**Resources:**
|
||||
- [RFC/spec/documentation] - [What to focus on]
|
||||
- [Blog post/paper] - [Key insights]
|
||||
|
||||
### Challenge 7: [Another Advanced Feature]
|
||||
|
||||
[Continue pattern]
|
||||
|
||||
## Expert Challenges
|
||||
|
||||
### Challenge 8: [Major Feature Requiring Significant Work]
|
||||
|
||||
**What to build:**
|
||||
[Ambitious extension that changes how the system works]
|
||||
|
||||
**Estimated time:**
|
||||
[Realistic estimate - days or weeks]
|
||||
|
||||
**Prerequisites:**
|
||||
You should have completed [earlier challenges] first because this builds on [concepts].
|
||||
|
||||
**What you'll learn:**
|
||||
- [Expert level concept 1]
|
||||
- [Expert level concept 2]
|
||||
- [Real world engineering skill]
|
||||
|
||||
**Planning this feature:**
|
||||
|
||||
Before you code, think through:
|
||||
- How does this affect existing functionality?
|
||||
- What are the performance implications?
|
||||
- How do you migrate existing data/users?
|
||||
- What's your rollback plan if it breaks?
|
||||
|
||||
**High level architecture:**
|
||||
|
||||
```
|
||||
[Detailed architecture diagram of the new feature]
|
||||
```
|
||||
|
||||
**Implementation phases:**
|
||||
|
||||
**Phase 1: Foundation** (X-Y hours)
|
||||
- [What to build first]
|
||||
- [Why this order]
|
||||
|
||||
**Phase 2: Core Feature** (X-Y hours)
|
||||
- [Main functionality]
|
||||
- [Key algorithms/logic]
|
||||
|
||||
**Phase 3: Integration** (X-Y hours)
|
||||
- [Connect to existing system]
|
||||
- [Handle compatibility]
|
||||
|
||||
**Phase 4: Polish** (X-Y hours)
|
||||
- [Error handling]
|
||||
- [Performance optimization]
|
||||
- [Documentation]
|
||||
|
||||
**Testing strategy:**
|
||||
- [Test type 1]: [What to verify]
|
||||
- [Test type 2]: [Scenarios to cover]
|
||||
- [Test type 3]: [Edge cases]
|
||||
|
||||
**Known challenges:**
|
||||
1. **[Challenge 1]**
|
||||
- Problem: [What goes wrong]
|
||||
- Hint: [Direction toward solution]
|
||||
|
||||
2. **[Challenge 2]**
|
||||
- Problem: [Issue]
|
||||
- Hint: [Guidance]
|
||||
|
||||
**Success criteria:**
|
||||
Your implementation should:
|
||||
- [ ] [Requirement 1]
|
||||
- [ ] [Requirement 2]
|
||||
- [ ] [Requirement 3]
|
||||
- [ ] Handle [edge case]
|
||||
- [ ] Pass [performance benchmark]
|
||||
|
||||
### Challenge 9: [Another Expert Challenge]
|
||||
|
||||
[Continue pattern]
|
||||
|
||||
## Mix and Match
|
||||
|
||||
Combine features for bigger projects:
|
||||
|
||||
**Project Idea 1: [Combined Feature Set]**
|
||||
- Combine Challenge X + Challenge Y
|
||||
- Add [new integration]
|
||||
- Result: [What you end up with]
|
||||
|
||||
**Project Idea 2: [Another Combination]**
|
||||
- [Details]
|
||||
|
||||
## Real World Integration Challenges
|
||||
|
||||
### Integrate with [External System/API]
|
||||
|
||||
**The goal:**
|
||||
Make this project work with [real service].
|
||||
|
||||
**What you'll need:**
|
||||
- [Service] account/API key
|
||||
- Understanding of [protocol/API]
|
||||
- Handle [authentication method]
|
||||
|
||||
**Implementation plan:**
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
**Watch out for:**
|
||||
- [Rate limits]
|
||||
- [Authentication refresh]
|
||||
- [Error handling]
|
||||
|
||||
### Deploy to [Platform]
|
||||
|
||||
**The goal:**
|
||||
Get this running in production on [cloud platform/service].
|
||||
|
||||
**What you'll learn:**
|
||||
- [Infrastructure as code]
|
||||
- [Deployment automation]
|
||||
- [Production monitoring]
|
||||
|
||||
**Steps:**
|
||||
1. [Infrastructure setup]
|
||||
2. [Configuration management]
|
||||
3. [Deployment pipeline]
|
||||
4. [Monitoring setup]
|
||||
|
||||
**Production checklist:**
|
||||
- [ ] [Security requirement]
|
||||
- [ ] [Performance requirement]
|
||||
- [ ] [Monitoring requirement]
|
||||
- [ ] [Backup/recovery]
|
||||
|
||||
## Performance Challenges
|
||||
|
||||
### Challenge: Handle [Scale Metric]
|
||||
|
||||
**The goal:**
|
||||
Make this system handle [specific load] without falling over.
|
||||
|
||||
**Current bottleneck:**
|
||||
[Component] can only handle [current limit] because [reason].
|
||||
|
||||
**Optimization approaches:**
|
||||
|
||||
**Approach 1: [Technique]**
|
||||
- How: [Implementation]
|
||||
- Gain: [Performance improvement]
|
||||
- Tradeoff: [What you give up]
|
||||
|
||||
**Approach 2: [Another technique]**
|
||||
- How: [Details]
|
||||
- Gain: [Improvement]
|
||||
- Tradeoff: [Cost]
|
||||
|
||||
**Benchmark it:**
|
||||
```bash
|
||||
[Load testing command]
|
||||
```
|
||||
|
||||
Target metrics:
|
||||
- [Metric 1]: [Goal]
|
||||
- [Metric 2]: [Goal]
|
||||
|
||||
### Challenge: Reduce [Resource Usage]
|
||||
|
||||
**The goal:**
|
||||
Cut [memory/CPU/bandwidth] usage by [percentage].
|
||||
|
||||
**Profile first:**
|
||||
```bash
|
||||
[profiling command]
|
||||
```
|
||||
|
||||
**Common optimization areas:**
|
||||
- [Area 1]: [What's inefficient, how to fix]
|
||||
- [Area 2]: [Details]
|
||||
|
||||
## Security Challenges
|
||||
|
||||
### Challenge: Add [Security Feature]
|
||||
|
||||
**What to implement:**
|
||||
[Specific security mechanism]
|
||||
|
||||
**Threat model:**
|
||||
This protects against:
|
||||
- [Attack 1]
|
||||
- [Attack 2]
|
||||
|
||||
**Implementation:**
|
||||
[Where to add it, how it works]
|
||||
|
||||
**Testing the security:**
|
||||
- Try to [bypass method 1]
|
||||
- Attempt [attack vector 2]
|
||||
- Verify [security property holds]
|
||||
|
||||
### Challenge: Pass [Security Standard]
|
||||
|
||||
**The goal:**
|
||||
Make this project compliant with [OWASP/CIS/NIST standard].
|
||||
|
||||
**Current gaps:**
|
||||
- [Gap 1]: [What's missing]
|
||||
- [Gap 2]: [What needs fixing]
|
||||
|
||||
**Remediation:**
|
||||
[How to address each gap]
|
||||
|
||||
## Contribution Ideas
|
||||
|
||||
Finished a challenge? Share it back:
|
||||
|
||||
1. **Fork the repo**
|
||||
2. **Implement your extension** in a new branch
|
||||
3. **Document it** - add to learn folder
|
||||
4. **Submit a PR** with:
|
||||
- Your implementation
|
||||
- Tests
|
||||
- Documentation
|
||||
- Example usage
|
||||
|
||||
Good extensions might get merged into the main project.
|
||||
|
||||
## Challenge Yourself Further
|
||||
|
||||
### Build Something New
|
||||
|
||||
Use the concepts you learned here to build:
|
||||
- [Related tool 1] - [What it would do]
|
||||
- [Related tool 2] - [Purpose]
|
||||
- [Variation] - [How it's different]
|
||||
|
||||
### Study Real Implementations
|
||||
|
||||
Compare your implementation to production tools:
|
||||
- [Tool 1] - [What they do differently]
|
||||
- [Tool 2] - [Interesting design choices]
|
||||
|
||||
Read their code, understand their tradeoffs, steal their good ideas.
|
||||
|
||||
### Write About It
|
||||
|
||||
Document your extension:
|
||||
- Blog post explaining [what you built]
|
||||
- Tutorial for others to follow
|
||||
- Comparison with [alternative approach]
|
||||
|
||||
Teaching others is the best way to verify you understand it.
|
||||
|
||||
## Getting Help
|
||||
|
||||
Stuck on a challenge?
|
||||
|
||||
1. **Debug systematically**
|
||||
- What did you expect?
|
||||
- What actually happened?
|
||||
- What's the smallest test case that reproduces it?
|
||||
|
||||
2. **Read the existing code**
|
||||
- [Similar feature] does something related
|
||||
- [Component] might have the pattern you need
|
||||
|
||||
3. **Search for similar problems**
|
||||
- [Forum/community]
|
||||
- [Stack Overflow tag]
|
||||
|
||||
4. **Ask for help**
|
||||
- Post in [discussion forum]
|
||||
- Include: what you tried, what happened, what you expected
|
||||
- Don't just paste error messages - explain your understanding
|
||||
|
||||
## Challenge Completion
|
||||
|
||||
Track your progress:
|
||||
|
||||
- [ ] Easy Challenge 1
|
||||
- [ ] Easy Challenge 2
|
||||
- [ ] Easy Challenge 3
|
||||
- [ ] Intermediate Challenge 4
|
||||
- [ ] Intermediate Challenge 5
|
||||
- [ ] Advanced Challenge 6
|
||||
- [ ] Advanced Challenge 7
|
||||
- [ ] Expert Challenge 8
|
||||
- [ ] Expert Challenge 9
|
||||
|
||||
Completed all of them? You've mastered this project. Time to build something new or contribute back to the community.
|
||||
|
|
@ -0,0 +1,116 @@
|
|||
# Learn Folder Checklist
|
||||
|
||||
Quick reference for what to include in each file.
|
||||
|
||||
## 00-OVERVIEW.md
|
||||
|
||||
- [ ] **What This Is** - 2-3 sentence project description
|
||||
- [ ] **Why This Matters** - Real world problem it solves
|
||||
- [ ] **Real world scenarios** - 3 specific use cases
|
||||
- [ ] **What You'll Learn** - Security concepts, technical skills, tools
|
||||
- [ ] **Prerequisites** - Required knowledge, tools needed, nice-to-haves
|
||||
- [ ] **Quick Start** - Installation steps that work
|
||||
- [ ] **Project Structure** - Key directories and files
|
||||
- [ ] **Next Steps** - Links to other learn files
|
||||
- [ ] **Common Issues** - 2-3 frequent problems with solutions
|
||||
- [ ] **Related Projects** - Links to similar projects
|
||||
|
||||
## 01-CONCEPTS.md
|
||||
|
||||
- [ ] **Primary Concept** - What it is, why it matters, how it works
|
||||
- [ ] **Common Attacks** - 3+ specific attack techniques
|
||||
- [ ] **Defense Strategies** - How to protect against attacks
|
||||
- [ ] **Secondary Concept** - Same structure
|
||||
- [ ] **Common Pitfalls** - Code examples of mistakes vs correct approach
|
||||
- [ ] **How Concepts Relate** - Connection diagram
|
||||
- [ ] **Industry Standards** - OWASP, MITRE, CWE mappings
|
||||
- [ ] **Real World Examples** - 2+ actual incidents/breaches
|
||||
- [ ] **Testing Your Understanding** - 3+ questions
|
||||
- [ ] **Further Reading** - Essential and deep dive resources
|
||||
|
||||
## 02-ARCHITECTURE.md
|
||||
|
||||
- [ ] **High Level Architecture** - ASCII diagram with components
|
||||
- [ ] **Component Breakdown** - Purpose and responsibilities of each
|
||||
- [ ] **Data Flow** - Step by step walkthrough with code references
|
||||
- [ ] **Design Patterns** - Patterns used, why, trade-offs
|
||||
- [ ] **Layer Separation** - If applicable, explain layers
|
||||
- [ ] **Data Models** - Key structures with field explanations
|
||||
- [ ] **Security Architecture** - Threat model and defense layers
|
||||
- [ ] **Storage Strategy** - What's stored where and why
|
||||
- [ ] **Configuration** - Environment variables and strategy
|
||||
- [ ] **Performance Considerations** - Bottlenecks and optimizations
|
||||
- [ ] **Design Decisions** - Major choices, alternatives, trade-offs
|
||||
- [ ] **Deployment Architecture** - How it runs in production
|
||||
- [ ] **Error Handling** - Strategy for different error types
|
||||
- [ ] **Extensibility** - Where and how to add features
|
||||
- [ ] **Limitations** - Current architectural constraints
|
||||
- [ ] **Comparison** - How this differs from similar systems
|
||||
|
||||
## 03-IMPLEMENTATION.md
|
||||
|
||||
- [ ] **File Structure** - Walkthrough of directory layout
|
||||
- [ ] **Building Core Feature 1** - Step by step with code
|
||||
- [ ] **Building Core Feature 2** - Same structure
|
||||
- [ ] **Security Implementation** - How security features work
|
||||
- [ ] **Data Flow Example** - Complete request trace through system
|
||||
- [ ] **Error Handling** - Patterns with code examples
|
||||
- [ ] **Performance Optimizations** - Before/after with benchmarks
|
||||
- [ ] **Configuration Management** - Loading and validation
|
||||
- [ ] **Database Operations** - CRUD with transaction handling
|
||||
- [ ] **Integration Points** - External systems/APIs
|
||||
- [ ] **Testing Strategy** - Unit and integration test examples
|
||||
- [ ] **Common Pitfalls** - Mistakes with symptoms, causes, fixes
|
||||
- [ ] **Debugging Tips** - How to troubleshoot common issues
|
||||
- [ ] **Code Organization** - Why files structured this way
|
||||
- [ ] **Extending the Code** - Template for adding features
|
||||
- [ ] **Code Style** - Linting, formatting, type annotations
|
||||
- [ ] **Dependencies** - Why each dependency, security scanning
|
||||
- [ ] **Build and Deploy** - Commands for building and running
|
||||
|
||||
## 04-CHALLENGES.md
|
||||
|
||||
- [ ] **Easy Challenges** (3+) - Simple extensions with hints
|
||||
- [ ] **Intermediate Challenges** (2+) - More complex features
|
||||
- [ ] **Advanced Challenges** (2+) - Significant new capabilities
|
||||
- [ ] **Expert Challenges** (1+) - Major features with detailed planning
|
||||
- [ ] **Mix and Match** - Combined project ideas
|
||||
- [ ] **Real World Integration** - External system connections
|
||||
- [ ] **Performance Challenges** - Scale and optimization tasks
|
||||
- [ ] **Security Challenges** - Additional security features
|
||||
- [ ] **Contribution Ideas** - How to share back
|
||||
- [ ] **Challenge Yourself Further** - Build new things, study others
|
||||
- [ ] **Getting Help** - Debugging and asking for help
|
||||
- [ ] **Challenge Completion** - Checklist to track progress
|
||||
|
||||
## For Each Challenge
|
||||
|
||||
- [ ] **What to build** - Specific feature description
|
||||
- [ ] **Why it's useful** - Real world application
|
||||
- [ ] **What you'll learn** - Skills and concepts
|
||||
- [ ] **Hints** - Guidance without full solution
|
||||
- [ ] **Test it works** - Verification steps
|
||||
|
||||
## Writing Quality Checks
|
||||
|
||||
- [ ] No em dashes (use periods or commas)
|
||||
- [ ] Minimal "it's not X, it's Y" contrast flips
|
||||
- [ ] Inconsistent hyphenation (mix it up)
|
||||
- [ ] Concrete examples, not abstractions
|
||||
- [ ] Real code from the project (not toy examples)
|
||||
- [ ] File and line number references
|
||||
- [ ] ASCII diagrams where helpful
|
||||
- [ ] Real world incidents referenced
|
||||
- [ ] Common mistakes shown
|
||||
- [ ] Human voice (not AI marketing speak)
|
||||
|
||||
## Before Publishing
|
||||
|
||||
- [ ] All links work
|
||||
- [ ] Code examples tested
|
||||
- [ ] Quick start instructions verified
|
||||
- [ ] Consistent formatting
|
||||
- [ ] No placeholder text left
|
||||
- [ ] Reviewed by someone else if possible
|
||||
- [ ] Spelling and grammar checked
|
||||
- [ ] Makes sense to someone unfamiliar with the project
|
||||
|
|
@ -0,0 +1,264 @@
|
|||
# Learn Folder Template
|
||||
|
||||
This directory contains templates for creating consistent, high quality educational documentation for each project.
|
||||
|
||||
## What Goes in a learn/ Folder
|
||||
|
||||
Every completed project should have a `learn/` directory with these four files:
|
||||
|
||||
1. **00-OVERVIEW.md** - Project introduction, prerequisites, quick start
|
||||
2. **01-CONCEPTS.md** - Security concepts and theory
|
||||
3. **02-ARCHITECTURE.md** - System design and technical decisions
|
||||
4. **03-IMPLEMENTATION.md** - Code walkthrough and how to build it
|
||||
5. **04-CHALLENGES.md** - Extension ideas and next steps
|
||||
|
||||
## Using These Templates
|
||||
|
||||
### For New Projects
|
||||
|
||||
When you start a new project:
|
||||
|
||||
1. Copy this entire template directory to your project:
|
||||
```bash
|
||||
cp -r .github/learn-folder-template PROJECTS/[difficulty]/[project-name]/learn
|
||||
cd PROJECTS/[difficulty]/[project-name]/learn
|
||||
```
|
||||
|
||||
2. Remove this README (you don't need it in the project):
|
||||
```bash
|
||||
rm README.md
|
||||
```
|
||||
|
||||
3. Fill in each template:
|
||||
- Replace `[placeholders]` with actual content
|
||||
- Delete sections that don't apply
|
||||
- Add sections specific to your project
|
||||
- Keep the overall structure
|
||||
|
||||
4. Write as you build - don't wait until the end
|
||||
|
||||
### For Existing Projects
|
||||
|
||||
Backfilling learn/ folders:
|
||||
|
||||
1. Start with 00-OVERVIEW.md - this is the easiest
|
||||
2. Then do 01-CONCEPTS.md - what security ideas does this teach?
|
||||
3. Then 02-ARCHITECTURE.md - how is it designed?
|
||||
4. Then 03-IMPLEMENTATION.md - walk through the actual code
|
||||
5. Finally 04-CHALLENGES.md - how can others extend it?
|
||||
|
||||
Don't try to do all files at once. One file per session works fine.
|
||||
|
||||
## Writing Guidelines
|
||||
|
||||
### Tone and Style
|
||||
|
||||
**Do:**
|
||||
- Write like you're explaining to a smart friend
|
||||
- Use concrete examples and real code
|
||||
- Explain WHY, not just WHAT
|
||||
- Reference actual vulnerabilities and incidents
|
||||
- Show common mistakes and how to avoid them
|
||||
- Use diagrams and code snippets liberally
|
||||
|
||||
**Don't:**
|
||||
- Sound like a marketing brochure
|
||||
- Use buzzwords without explaining them
|
||||
- Assume the reader knows everything (or nothing)
|
||||
- Write walls of text - break it up
|
||||
- Skip the hard parts
|
||||
|
||||
### Content Depth
|
||||
|
||||
**00-OVERVIEW.md** - Surface level, get them excited and oriented
|
||||
- 5-10 minute read
|
||||
- Focus on what and why
|
||||
- Light on technical details
|
||||
|
||||
**01-CONCEPTS.md** - Medium depth, teach the theory
|
||||
- 15-20 minute read
|
||||
- Explain security concepts thoroughly
|
||||
- Use examples and diagrams
|
||||
- Reference standards (OWASP, MITRE, etc)
|
||||
|
||||
**02-ARCHITECTURE.md** - Deep dive on system design
|
||||
- 20-30 minute read
|
||||
- Show the big picture
|
||||
- Explain design decisions and tradeoffs
|
||||
- Include diagrams
|
||||
|
||||
**03-IMPLEMENTATION.md** - Deepest, actual code walkthrough
|
||||
- 30-45 minute read
|
||||
- Reference real files and line numbers
|
||||
- Show actual code from the project
|
||||
- Explain step by step
|
||||
|
||||
**04-CHALLENGES.md** - Mixed depth based on difficulty
|
||||
- 10-15 minute read
|
||||
- Range from easy to expert
|
||||
- Provide hints, not full solutions
|
||||
- Encourage experimentation
|
||||
|
||||
### Code Examples
|
||||
|
||||
Always show real code from the actual project, not toy examples:
|
||||
|
||||
```python
|
||||
# Good - actual code from the project
|
||||
# src/auth/service.py:42-56
|
||||
async def authenticate_user(email: str, password: str) -> User:
|
||||
user = await user_repo.find_by_email(email)
|
||||
if not user or not verify_password(password, user.password_hash):
|
||||
raise InvalidCredentials()
|
||||
return user
|
||||
```
|
||||
|
||||
```python
|
||||
# Bad - generic example
|
||||
def login(username, password):
|
||||
# check if valid
|
||||
return user
|
||||
```
|
||||
|
||||
### Avoiding AI Voice
|
||||
|
||||
Watch out for these telltale AI patterns:
|
||||
|
||||
**Em dashes** - Don't use them. Use periods or commas instead.
|
||||
```
|
||||
Bad: "It's not just about security — it's about building robust systems"
|
||||
Good: "This teaches security and system design"
|
||||
```
|
||||
|
||||
**Contrast flips** - The "it's not X, it's Y" pattern
|
||||
```
|
||||
Bad: "It's not about memorizing syntax — it's about understanding concepts"
|
||||
Good: "Focus on understanding concepts, not memorizing syntax"
|
||||
```
|
||||
|
||||
**Perfect hyphenation** - Don't hyphenate every compound modifier
|
||||
```
|
||||
Bad: "real-time analysis using state-of-the-art machine-learning algorithms"
|
||||
Good: "real-time analysis using state of the art machine learning algorithms"
|
||||
```
|
||||
|
||||
Mix it up. Sometimes hyphenate, sometimes don't. Humans are inconsistent.
|
||||
|
||||
**Generic enthusiasm**
|
||||
```
|
||||
Bad: "Embark on an exciting journey into the world of cybersecurity!"
|
||||
Good: "Learn how rate limiting works by building one from scratch"
|
||||
```
|
||||
|
||||
### Diagrams
|
||||
|
||||
ASCII diagrams work great:
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Client │
|
||||
└──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ API │
|
||||
└──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ Database │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
Use them for:
|
||||
- Architecture overviews
|
||||
- Data flow
|
||||
- State machines
|
||||
- Layer diagrams
|
||||
|
||||
### Real World References
|
||||
|
||||
Ground concepts in reality:
|
||||
|
||||
**Good:**
|
||||
"In the 2017 Equifax breach, attackers exploited a known Apache Struts vulnerability (CVE-2017-5638). This project teaches you how to scan for such vulnerabilities in your dependencies."
|
||||
|
||||
**Bad:**
|
||||
"In today's evolving threat landscape, vulnerability management is critical."
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before submitting a learn/ folder, check:
|
||||
|
||||
### 00-OVERVIEW.md
|
||||
- [ ] Explains what the project does in 2-3 sentences
|
||||
- [ ] Lists specific prerequisites with examples
|
||||
- [ ] Includes quick start instructions that work
|
||||
- [ ] Shows expected output
|
||||
- [ ] Links to other learn/ files
|
||||
|
||||
### 01-CONCEPTS.md
|
||||
- [ ] Explains each security concept thoroughly
|
||||
- [ ] Includes real world examples or breaches
|
||||
- [ ] Shows common attacks and defenses
|
||||
- [ ] References OWASP/MITRE/CWE where relevant
|
||||
- [ ] Includes "testing your understanding" questions
|
||||
|
||||
### 02-ARCHITECTURE.md
|
||||
- [ ] High level architecture diagram
|
||||
- [ ] Component breakdown
|
||||
- [ ] Design decisions with reasoning
|
||||
- [ ] Data flow examples
|
||||
- [ ] Performance and security considerations
|
||||
|
||||
### 03-IMPLEMENTATION.md
|
||||
- [ ] References actual files and line numbers
|
||||
- [ ] Shows real code from the project
|
||||
- [ ] Explains WHY, not just WHAT
|
||||
- [ ] Includes common pitfalls
|
||||
- [ ] Provides debugging tips
|
||||
|
||||
### 04-CHALLENGES.md
|
||||
- [ ] Mix of difficulty levels
|
||||
- [ ] Specific, actionable challenges
|
||||
- [ ] Hints without full solutions
|
||||
- [ ] Real world applications
|
||||
- [ ] Connection to other projects
|
||||
|
||||
### General
|
||||
- [ ] No em dashes
|
||||
- [ ] Minimal "it's not X, it's Y" patterns
|
||||
- [ ] Inconsistent hyphenation (like a human)
|
||||
- [ ] Concrete examples, not abstractions
|
||||
- [ ] Code examples are real, not toys
|
||||
- [ ] Diagrams where helpful
|
||||
- [ ] Links work
|
||||
- [ ] Formatting is consistent
|
||||
|
||||
## Examples
|
||||
|
||||
Good examples to reference:
|
||||
|
||||
- **PROJECTS/advanced/bug-bounty-platform/learn/** - Comprehensive, well structured
|
||||
- **PROJECTS/advanced/api-rate-limiter/learn/** - Good technical depth
|
||||
|
||||
These aren't perfect but they're solid templates to learn from.
|
||||
|
||||
## Getting Help
|
||||
|
||||
Questions about writing learn/ docs?
|
||||
|
||||
1. Look at existing examples
|
||||
2. Ask in discussions
|
||||
3. Draft one file and get feedback before doing all five
|
||||
4. Iterate based on feedback
|
||||
|
||||
## Contributing Improvements
|
||||
|
||||
Found ways to improve these templates?
|
||||
|
||||
1. Make changes to `.github/learn-folder-template/`
|
||||
2. Submit PR with explanation
|
||||
3. Update this README if structure changes
|
||||
|
||||
The templates should evolve as we learn what works best.
|
||||
Loading…
Reference in New Issue