Assignment 4 - Tech Choices, Architecture Diagram, Roadmap

The intention of this assignment is to get an initial sense of the direction of your engineering focus. By now you should have had enough time with your teams to know what you’re building. Given the project and the skills in your team, the goal of this assignment is to choose a tech stack, design an architecture diagram for your application, and fill out a roadmap.

None of this is set in stone. These are initial plans and I will be highly sceptical if they are executed exactly as you plan here. The idea of this assignment is to get an initial sense of what you intend to do, the scope of work, and start planning the rest of the terms work.

Since you can change your decision from this initial starting point, you should keep track of it. You will be expected to record in some way why the pivot happened and what caused the pivot to happen. A GitHub issue is a recommended place to record this decision.

You will be expected to work together and submit this assignment as a team. Anyone can submit it, I suggest using an issue on the team repo you created in A1 to coordinate that submission.



Requirements

  1. Product Requirements: Based on your CUJs, discuss the product requirements with all members of your team.
    • Documentation: Record all components in the team repository under product_research/use_cases.md.
    • JTBD: Call out the “jobs to be done” that your product will accomplish. You can have one more then. All crucial user journeys (CUJs) must tie back to solving a JTBD. You can have more than one JTBD.
      • As a [user persona], I want to [goal/task], so that I can [value or outcome].
    • CUJs: Develop at least 3 CUJs and no more than 6 that you will implement for your MVP. Indicate how the CUJ
      • Concise statement or example of that the user can do.
        1. Ex: The user clicks a button and selects files to upload. They click a run button and the UI returns a filled out tax return.
      • Description & UI/UX: Clearly define each use case with accompanying low-fidelity UI/UX sketches to illustrate functionality.
      • Clarity for Marking: Provide sufficient detail for teaching staff to evaluate subsequent assignments.
      • Approval: Obtain approval from CSC491/2600 teaching staff to confirm appropriate complexity for the course and simplicity for the MVP stage.
    • Functional / Non-Functional requirements: Outline what’s needed to be included on your product. These requirements will then be broken down and sequenced in your roadmap.
    • Technical Alignment: Ensure use cases align with the proposed tech stack and architecture diagram.
  2. Architecture Diagram: Design your tech stack. Once that is complete, with the technical members of your team, design an intended architecture diagram.
    • In your team’s Github repository, find the architecture/adrs directory. Document your team’s technology stack within this architecture directory.
    • Each decision, including considered but unselected tools and those being phased out, needs a separate ADR markdown.
    • Update these decisions with new ADRs whenever the technology stack changes to maintain a comprehensive record.
    • The diagram should not be highly detailed as you have just started. You’ll be using this to help guide your work.
    • It should include all pieces of your production infrastructure (emails, databases, caches, servers, email, background jobs, ML models, etc)
    • Include a short write up explaining anything that is not obvious.
  3. Roadmap
    • Using the GitHub Projects feature, GitHub Issues, and GitHub Milestones record and intended roadmap.
    • The roadmap should include implementation of all pieces of your infrastructure, testing infrastructure, and development environment. All items in your Stack Decisions should be accounted for as well.
    • Setup a roadmap. The roadmap must go past the end of the term. The roadmap can include as much detail as you want with the following conditions:
      • Pretend like you are planning a company, not a class project
      • Must include your immediate next steps (short term up to end of the next month), medium term (up to 6 months in the future), and long term (6+ months).
      • Must include plans to perform user research
      • Must include low-fidelity plans for a launch date
      • You fill in the gaps. Be careful not to go too detailed as we have limited knowledge still.

None of this information is set in stone. Provide a basic insight into your initial thought processes, change the repo and Stack Decisions as these insights evolve throughout the course.

Architecture Diagram

An architecture digram can be made in many different applications. Some common ones you’ll probably come across are LucidChart, Excalidraw, Figma (Jams), Google Drawing, and MermaidJS (programmatic, not super powerful). When it comes to your diagram, I expect it to make sense and be grouped logically. It should try to indicate similar pieces of the architecture and make the paths between nodes flow smoothly.

Below are 2 examples of the same architecture diagram. These are real diagrams that we made for the Slack Application at GitHub.

Needs ImprovementGood!
This diagram, while it has all the pieces, failed to group the different systems together. The data sources (3rd party APIs) are even on different sides of the diagram. Logos are all different sizes, and arrows aren’t as smooth as they can be.This diagram has all the same information, however we have logically grouped the pieces into data sources, data storage, and monitoring. This gives the reader a clear indication of intent and architecture. This diagram made sure the logos were all the same size as size could indicate something like important, which we were not trying to do here. We also reduced the clutter of the arrows and removed all angles. This makes the diagram far easier to read and understand

Your diagram should follow these same principles. You do not need to include pieces of your stack that don’t touch production (e.g. GitHub), but should include all tools that do (like monitoring). You can see an alternative format in the F2019 team Klutch (you should note this repo came from a previous iteration of this course, so some of the instruction was different. If you are unsure about something, err on the side of caution and use this term’s instructions or ask me).

What is the purpose of this assignment?

This assignment helps you plan out the main use cases of your application and scope down the amount of work you can realistically achieve. The architecture diagram and stack choices help you to choose a good path, and are exercises often seen in industry when starting new services.

We expect all CSC491/2600 students to actively participate and have thoughtful discussions around which technologies to choose. Best practices lessons should be watched first in order to effectively complete this assignment.

Submission

You must create a release on your repo. This will give us a snapshot in time and allow us to grade it. See release body criteria and example below. Assignments without a coherent release body that follow the instructions in this assignment will be rejected and marked 1 day late.

One member of your team (could be the team leader, or any other leader) must submit a link to the release in Quercus for ‘Assignment 3 - Tech Choices, Architecture Diagram, Roadmap’. Only one team member needs do this.

Assignments are always due at 11:59:59pm Eastern Time.

Release Body

Release bodies must include:

Example release body demonstrating the written instructions

Questions or Concerns?

Rubric

Product Requirements (40%)

CriteriaDescriptionWeight
JTBD StatementsWell-articulated and actionable JTBDs tied closely to user needs and goals. Clear connection to CUJs.10%
CUJs + UI/UX Sketches3–6 CUJs that clearly connect to JTBDs and show thoughtful user flow. Includes relevant low-fidelity UI/UX sketches.15%
Functional / Non-Functional RequirementsComprehensive, well-organized list that accurately reflects scope, constraints, and system needs. These requirements are later reflected in the architecture and roadmap.10%
Documentation & Clarity for MarkingAll product research and requirements are well-documented in the correct location in the repo (product_research/use_cases.md). Clear and easy to understand for TAs.5%

Architecture Design (40%)

CriteriaDescriptionWeight
Tech Stack Selection & JustificationJustify technology stack choices, detailing how each addresses specific use cases, aligns with project scope, and fulfills product requirements. Discuss trade-offs and provide comprehensive justification for any technology not fully meeting a requirement.15%
Architecture DiagramClear, high-level diagram including all major components (DB, server, cache, etc). Appropriate level of abstraction. Includes a short write-up for clarity.10%
Technical Alignment with Use CasesStrong consistency between the chosen tech stack, architecture design, and the CUJs. Design supports planned features.10%
ADR Documentation (Architecture Decision Records)All major decisions are documented in separate ADRs. Includes rationale, alternatives considered, and future update plans.5%

Roadmap (20%)

CriteriaDescriptionWeight
Roadmap Structure & DetailRoadmap is structured with short-, mid-, and long-term plans. All major components (infra, dev/test env, stack decisions) are represented.10%
User Research & Launch PlanningRoadmap includes plans for user research and outlines a plausible low-fidelity launch timeline.5%
GitHub Integration (Projects / Milestones / Issues)Roadmap effectively uses GitHub tools (Projects, Milestones, Issues). Items are well-labeled and logically sequenced.5%

Notes

Rating Scale

This scale is used for each line of the rubric above.

RatingResult
Outstanding100% of pts
Strong80% of pts
Acceptable60% of pts
Insufficient40% of pts
Unacceptable0% of pts