Skip to content

Submission Requirements

What to Submit

Your submission must include all deliverables from Parts 1-4, plus optional bonus work.

Submission Format

1. Code Repository

Submit a GitHub repository (or zip file) containing:

rpc-calculator/
├── proto/
│   └── calculator.proto
├── server.py
├── client.py
├── circuit_breaker.py
├── tests/
│   ├── test_part1.py
│   ├── test_part2.py
│   ├── test_part3.py
│   └── test_part4.py
├── requirements.txt
├── README.md
└── docs/
    └── report.pdf

Code Quality Requirements:

  • ✅ Clean, readable code with consistent style
  • ✅ Meaningful variable and function names
  • ✅ Docstrings for all major functions/classes
  • ✅ Type hints where appropriate
  • ✅ No hardcoded values (use configuration)
  • ✅ Proper error handling

IMPORTANT: Proto File Constraint

The calculator.proto file is provided as part of the starter code and MUST NOT be modified. Your submission must use the provided proto file exactly as given. Any modifications to the proto file will result in deductions.

2. Video Demonstrations

Create 4 short videos (one per part):

  • Part 1: 1 minute - Basic RPC working
  • Part 2: 2 minutes - Failure handling and retries
  • Part 3: 2 minutes - Idempotency demonstration
  • Part 4: 2 minutes - Circuit breaker states

Video Requirements:

  • ✅ Screen recording showing terminal output
  • ✅ Clear narration explaining what's happening
  • ✅ Demonstrate all required test scenarios
  • ✅ Show both successes and failures
  • ✅ Upload to YouTube (unlisted) or Google Drive

3. Written Report

Submit a PDF report (3-5 pages) answering:

Part 1 Questions

  • How does gRPC serialize and deserialize messages?
  • What advantages does Protocol Buffers have over JSON?

Part 2 Questions

  • Why shouldn't we retry division-by-zero errors?
  • What happens if 1000 clients retry simultaneously? How does jitter help?
  • Is your calculator using at-least-once or at-most-once semantics?

Part 3 Questions

  • Why generate request_id before the first attempt?
  • What happens if the server's request cache fills up during retries?
  • Which operations are naturally idempotent? Why?
  • How would you make withdraw(account_id, amount) idempotent?

Part 4 Questions

  • Why "fail fast" when circuit is open?
  • What's the purpose of the HALF_OPEN state?
  • Where should circuit breakers be placed in microservices?
  • How to choose failure_threshold and timeout values?

Bonus Questions (if applicable)

  • Performance comparison results and analysis
  • When to use gRPC vs REST?
  • Trade-offs discussion

Report Format:

  • ✅ PDF format
  • ✅ 11pt font, single-spaced
  • ✅ Include code snippets where relevant
  • ✅ Include charts/graphs for performance data
  • ✅ Proper citations if using external sources

Submission Deadline

Due Date: [TBD - Check course syllabus]

Late Policy: [TBD - Check course syllabus]

Submission Checklist

Before submitting, verify:

Code Completeness

  • [ ] All 4 parts implemented and working
  • [ ] All test scripts included
  • [ ] requirements.txt with correct versions
  • [ ] README.md with setup instructions
  • [ ] No syntax errors or crashes

Documentation

  • [ ] Docstrings for all major functions
  • [ ] README explains how to run the project
  • [ ] Comments for complex logic
  • [ ] Type hints where applicable

Testing

  • [ ] All operations work correctly
  • [ ] Timeout handling demonstrated
  • [ ] Retry logic works with exponential backoff
  • [ ] Idempotency prevents duplicate increments
  • [ ] Circuit breaker transitions between states

Videos

  • [ ] 4 video links included in README
  • [ ] All videos are accessible (check permissions)
  • [ ] Videos show all required scenarios
  • [ ] Clear audio narration

Report

  • [ ] All analysis questions answered
  • [ ] Performance data included (if bonus)
  • [ ] PDF format, properly formatted
  • [ ] No typos or grammatical errors

Grading Weight

Component Weight
Part 1: Basic RPC 30%
Part 2: Failure Handling 35%
Part 3: Idempotency 20%
Part 4: Circuit Breaker 15%
Total 100%
Bonus: RPC vs REST +10%

See Grading Rubric for detailed breakdown.

Academic Integrity

Allowed Resources

  • ✅ Course materials and lecture slides
  • ✅ Official gRPC documentation
  • ✅ Stack Overflow for syntax/debugging
  • ✅ Discussion with classmates about concepts

Not Allowed

  • ❌ Copying code from GitHub repositories
  • ❌ Using AI to write entire implementations
  • ❌ Submitting someone else's work
  • ❌ Sharing your complete solution with others

Note: Using AI tools for learning (e.g., explaining concepts, debugging) is allowed, but you must understand and be able to explain all code you submit.

How to Submit

  1. Create a private GitHub repository
  2. Add your code and documentation
  3. Add instructor/TA as collaborator
  4. Submit repository link via course portal

Option 2: Zip File

  1. Create zip file of your project directory
  2. Ensure all files are included
  3. Test by extracting and running
  4. Upload via course portal

Include in submission: - Repository URL or zip file - Video links (in README.md) - Report PDF

Getting Help

If you encounter issues:

  1. Check the documentation - Most common issues are covered
  2. Office hours - [TBD - Check course schedule]
  3. Discussion forum - Ask questions (without sharing solutions)
  4. Email TA/Instructor - For private issues

Response time: Expect 24-48 hour response during weekdays.

Frequently Asked Questions

Can I use a different port than 50051?

Yes, but document it clearly in your README.

Can I use Python 3.7 instead of 3.8+?

Yes, but ensure all code works. Type hints might need adjustment.

Do I need to implement TLS/SSL?

No, this assignment uses insecure channels for simplicity.

Can I use a different RPC framework?

No, the assignment requires gRPC specifically.

How long should my videos be?

Follow the suggested durations. Focus on quality over length.

Can I work with a partner?

[TBD - Check course policy]

What if my test scenarios don't work?

Debug thoroughly, document the issue, and explain what you tried. Partial credit is available.

Extensions

If you need an extension due to extenuating circumstances:

  1. Email instructor before the deadline
  2. Provide brief explanation
  3. Request specific extension duration

Last-minute requests without valid reasons may be denied.

Resubmission Policy

[TBD - Check course policy]

Questions?

Contact: - Instructor: [Email TBD] - TA: [Email TBD] - Office Hours: [Schedule TBD]