Outline

Course Description

From the course calendar:

CS 346 LAB,LEC,TST 0.50

Application Development

Introduction to full-stack application design and development. Students will work in project teams to design and build complete, working applications and services using standard tools. Topics include best-practices in design, development, testing, and deployment.

Prereq: CS 246; Computer Science students only

Course Requirements

This course is restricted to Computer Science students. You must have completed CS 246 prior to taking this course, and you should be able to:

• Design, code and debug small C++ programs using standard tools. e.g. GCC on Unix.
• Write effective unit tests for these programs. e.g. informal I/O tests, unit tests.
• Demonstrate programming proficiency in C++, which includes: understanding of fundamental OO concepts. e.g. abstraction, encapsulation; knowing how to use classes, objects, method overloading, and single inheritance; polymorphism; understanding how to use assertions, and how to manage exceptions.

Learning Objectives

On successful completion of the course, students will be able to:

• Work effectively as a member of a software development team.
• Use an interactive process to manage the design, development and testing of software projects.
• Design and develop different styles of application software in Kotlin, using appropriate architectural and design patterns.
• Design services that can provide remote capabilities to your application.
• Apply debugging and profiling techniques to address design and performance issues.
• Produce unit and integration tests as part of the development process.

Required Resources

There are no required textbooks for this course. This website is the primary source for reading material, recorded videos and other supporting materials. For those that want to pursue topics in greater detail, there are additional resources listed in each chapter.

You will need administrative access to a computer to work on the project. This system should be capable of running the toolchain described here. You will not be able to use lab machines for this course, since you do not have administrative rights on those machines.

Please check your system requirements early in the course, and ask the instructor if you have any concerns.

Course Staff

Faculty & Staff

• Dr. Jeff Avery (j2avery@). Course Instructor, responsible for course design and instruction (profile).
• Caroline Kierstead (ctkierst@). Instructional Support Coordinator (ISC), handles academic integrity and course accomodations.

Teaching Assistants (TA)

• Yiwen Dong (y225dong@)
• Deborah Etsenake (detsenak@)
• Shahpar Khan (s33khan@)
• Aniruddhan Murali (a25murali@)
• Gareema Ranjan (granjan@)

Contacting Us

We maintain Piazza forums where you can ask questions outside of class. We will try and keep up with questions asked during normal business hours (9 AM - 5 PM) but there is no guarantee of a prompt reply after-hours or on weekends.

You are also welcome to help one another out on the forums, of course! (Just avoid posting code).

Assessment

This course is designed around a single project that you will design and develop with your project team. Most course components are tied to the course project in some way. Team grade items are items where everyone on the team receives the same grade. Personal grade items are individual grades.

• Proposal: You need to provide details of your project, including a clear definition of your users, a problem to be solved, and the features that you will implement to address this problem. See project activities.
• Demos: During each sprint, you are expected to identify what requirements to address, assign and complete work, and have a product release ready to demo on the final day. You will be evaluated during the final demo. See project activities.
• Project Submission: Your final project submission is the complete contents of your GitLab repository, including README, Wiki documents, Releases pages, and Source code. See project submission for details.
• Participation: You are expected to meet regularly with your team, and participate in all aspects of the project. Your participation grade will be calculated at the end of the term, and will be based on project data (i.e. your relative contribution, out of 5 marks), and a score assigned by other team members (i.e. you will rate one another at the end of the project, out of 10).

Rating your team members

• At the end of Sprint 4, every person should send Jeff an email with a rating score for each of their team members.
• Rate their overall participation and effort in the course. “Did they contribute to the best of their ability?”
• Rate (1-10): 1 (very poor) -> 3 (poor) -> 5 (average) -> 7 (good) -> 8/9 (great!) -> 10 (carried the project)
• These should be anonymous!

Email format

• Title: Team 123 Participation Grades
• Body: Each person’s name and a single grade. You may write a comment if you wish but that is not required.

• Quizzes: All quizzes are available in LEARN during the week listed on the schedule. They open by 10:00 AM on the Monday morning, and close at 11:59 PM on the Friday of each week. Late submissions will NOT be accepted. Once you start the quiz, you must complete and submit it within 30 minutes. Each quiz covers to the content up to the week prior to the quiz being open in Learn.

Course Policies

Team Participation

The expectation in this course is that you will form teams in the first couple of weeks, and work together towards meeting project deliverables. The following guidelines apply:

• Students are responsible for matching up and forming teams. Teams must be formed by the end of the second week of the term (i.e. the add-course deadline). If you fail to find a team, you must inform the instructor by the end of the second week.
• We do not guarantee you a team after the end of the second week. If you have not joined a team, and have not made some arrangement with the instructor, you may be required to withdraw from the course.
• Course enrolment will be managed by the instructor to facilitate teams of four. If required, the instructor may authorize larger or smaller teams to accomodate everyone that is enrolled in the course.
• If you fail to participate in project activities in the weeks leading up to the project proposal, you may be removed from the course. This is necessary so that teams can launch their projects successfully!

Absences

Students are expected to attend lectures and demos with their team. Failing to attend a demo will normally result in a grade of zero for that course component.

However, we recognize that circumstances may sometimes require you to miss a demo e.g. coop interviews, testing positive for COVID. If you need to miss a demo, the following guidelines apply:

• You must contact the instructor and your teammates ahead of the due date. If missing a demo, you must coordinate with your team since they will be expected to proceed without you.
• You must provide the instructor with a reason for missing the component (e.g. illness/COVID).
• You are still expected to complete your work leading up to that deadline i.e. you are excused from presenting but not automatically excused for completing your work for the sprint!

The instructor will consider your request, and either (a) grant you an exemption from this component and redistribute the weight across other components, (b) grant you an extension, where you are expected to meet the requirement at a later date, or (c) not grant your request, in which case you have to either attend/contribute or accept a grade of zero. The decision to grant an exemption is at the discretion of the instructor.

Finally, you are allowed to miss at-most one demo per term without penalty, regardless of the reasons.

Self-Decaration

If you test positive for COVID or have COVID-symptoms, you are required to use the COVID self-declaration form. If you are ill but do not meet the COVID self-declaration guidelines, you should instead follow the guidelines and steps outlined in the Math Accommodations page.

In both cases, you must also follow the instructions listed above.

Short-Term Absence

You CANNOT use a short-term absence to delay a project demo (LAB components are exempt from STA requests). Contact the instructor if other assessments are affected.

Inclusiveness

It is our intent that students from all diverse backgrounds and perspectives are well-served by this course, and that student’s learning needs be addressed both in and out of class. We recognize the immense value of the diversity in identities, perspectives, and contributions that students bring, and the benefit it has on our educational environment. Your suggestions are encouraged and appreciated. Please let us know ways to improve the effectiveness of the course for you personally or for other students or student groups. In particular: 

• We will gladly honour your request to address you by an alternate/preferred name or gender pronoun. Please advise us of this preference early in the term so we may make appropriate changes to our records. 
• We will honour your religious holidays and celebrations. Please inform us of these at the start of the course. 
• We will follow AccessAbility Services guidelines and protocols on how to best support students with different learning needs. 

Academic Integrity

In order to maintain a culture of academic integrity, members of the University of Waterloo community are expected to promote honesty, trust, fairness, respect and responsibility. Contact the Office of Academic Integrity for more information. You are expected to follow the policies outlined above for quiz and project submissions.

To ensure academic integrity, MOSS (Measure of Software Similarities) is used in this course as a means of comparing student projects. We will report suspicious activity, and penalties for plagiarism/cheating are severe. Please read the available information about academic integrity very carefully.

Ethical Behaviour

Students are expected to act professionally, and engage one another in a respectful manner at all times. This expectation extends to working together in project teams. Harassment or other forms of personal attack will not be tolerated. Course staff will not referee interpersonal disputes on a project team; incidents will be dealt with according to Policy 33.

Plagiarism

Students are expected to either work on their own (in the case of quizzes), or work within a project team (for the remaining deliverables in the course). All work submitted should either be their own or created by the team for use in their project. However, we realize that it is common practice to use third-party libraries and sources found online to solve programming problems. For this reason, the team is allowed to use third-party source or libraries for their project provided that (a) they document the source of this contribution in source code, typically as a comment, and in their README file, and (b) no single source constitutes more than 10% of their project. Failure to acknowledge a source will result in a significant penalty (10% or more) of your final project grade, depending on the severity of the infraction. Note that MOSS will be used to compare student assignments, and that this rule also applies to copying from other student projects.

OpenAI & LLM

Use of OpenAI systems (including ChatGPT, CoPilot and similar systems) falls under the umbrella of plagiarism: it’s a source that you must cite, and it’s contribution cannot exceed more than 10% of your code (per above policy).

Reuse of Projects

You cannot base your project in part or in whole on coursework that you have completed for a different course. Similarly, you cannot submit the same project to multiple courses for credit (i.e. CS 346 and CS 446 would require different projects to be submitted that do not share code or any componets).

Student Discipline

A student is expected to know what constitutes academic integrity to avoid committing an academic offence, and to take responsibility for his/her actions. A student who is unsure whether an action constitutes an offence, or who needs help in learning how to avoid offences (e.g., plagiarism, cheating) or about ‘rules’ for group work/collaboration should seek guidance from the course instructor, academic advisor, or the undergraduate Associate Dean. For information on categories of offences and types of penalties, students should refer to Policy 71, Student Discipline. For typical penalties check Guidelines for the Assessment of Penalties.

Intellectual Property

Students should be aware that this course contains the intellectual property of their instructor, TA, and/or the University of Waterloo. Intellectual property includes items such as:

• Lecture content, spoken and written (and any audio/video recording thereof)
• Lecture handouts, presentations, and other materials prepared for the course (e.g., PowerPoint slides)
• Questions or solution sets from various types of assessments (e.g., assignments, quizzes, tests, final exams), and
• Work protected by copyright (e.g., any work authored by the instructor or TA or used by the instructor or TA with permission of the copyright owner).

Course materials and the intellectual property contained therein, are used to enhance a student’s educational experience. However, sharing this intellectual property without the intellectual property owner’s permission is a violation of intellectual property rights. For this reason, it is necessary to ask the instructor, TA and/or the University of Waterloo for permission before uploading and sharing the intellectual property of others online (e.g., to an online repository). Permission from an instructor, TA or the University is also necessary before sharing the intellectual property of others from completed courses with students taking the same/similar courses in subsequent terms/years. In many cases, instructors might be happy to allow distribution of certain materials. However, doing so without expressed permission is considered a violation of intellectual property rights.

Continuity Plan

As part of the University’s Continuity of Education Plan, every course should be designed with a plan that considers alternate arrangements for cancellations of classes and/or exams.

Here is how we will handle cancellations in this course, if they occur.

• In the case of minor disruptions (e.g. one lecture), the lecture content will be reorganized to fit the remaining time. This should not have any impact on demos or deliverables.

• Cancellation of multiple classes may result in a reduction in the number of sprints and associated deliverables to fit the remaining time. If this happens, lecture content will also be pruned to fit available time. Assessment weights will be redistributed evenly over the remaining content if required to align with the material.

• Cancellation of in-person (midterm or final) examinations has no effect on this course, since we do not have scheduled exams. Quizzes will continue to be written, but will be adjusted to the modified schedule as necessary.

Supports

Students with Disabilities

AccessAbility Services collaborates with all academic departments to arrange appropriate accommodations for students with temporary or permanent disabilities without compromising the academic integrity of the curriculum. If you require academic accommodations, please register with the AccessAbility Services at the beginning of each academic term. They will in-turn contact your instructors and arrange accomodations if necessary.

Mental Health Resources

If you or anyone you know experiences any academic stress, difficult life events, or feelings like anxiety or depression, we strongly encourage you to seek support.

On-Campus

• Campus Wellness: https://uwaterloo.ca/campus-wellness/ 
• Counselling Services: counselling.services@uwaterloo.ca. 519-888-4567 ext. 32655.
• MATES: one-to-one peer support program offered by Waterloo Undergraduate Student Association (WUSA) and Counselling Services: mates@wusa.ca
• Health Services: located across the creek from the Student Life Centre. 519-888-4096. 

Off-campus

• Good2Talk (24/7): Free confidential help line for post-secondary students. Phone: 1-866-925-5454 (Ontario and Nova Scotia only)
• Here 24/7: Mental Health and Crisis Service Team. Phone: 1-844-437-3247 (Waterloo Region only) 
• OK2BME: set of support services for lesbian, gay, bisexual, transgender, or questioning teens. Phone: 519-884-0000 extension 213 (Waterloo Region only)
• EMPOWER ME  1-833-628-5589 for Canada/USA. Other countries see: http://studentcare.ca/rte/en/IHaveAPlan_WUSA_EmpowerMe_EmpowerMe 
• EMPOWER ME in China:
  • China North  108007142831 
  • China South  108001402851 

Requirements

What is a full-stack application?

A full-stack application is an app that has a front-end/client component that runs on a personal device (computer, phone), and one or more back-end components that run on a remote system (server) to provide additional capabilities.

There are multiple reasons to design a software system this way:

• We might have data that needs to be shared across multiple devices, and backend services can manage access to that data.
• We might need additional capabilities that a backend service provides.

Image from Jake Northey, “Should We Use a Full Stack Development Team or Specialists?”

Many of the applications that you use are full-stack applications!

• A web browser is a front-end client for a remote web server that contains shared data/pages.
• A Twitter client pulls tweets from a number of online sources and presents them in a local client.
• Microsoft Word is mostly a local application, but it integrates with OneDrive (Microsoft’s remote storage solution) for document storage.
• Even a text editor like Visual Studio Code integrates with a number of remote services for automatic updates, maintaining extensions and so on.

You and your team will propose, design and build a full-stack application that runs locally but leverages one or more remote services (at least one of which you must design and write yourself).

What are your project requirements?

You can choose a project idea from the list below, or come up with your own idea. Regardless of which project you choose, you MUST meet some common requirements:

1. You are required to use our technology stack, which are the technologies that we will discuss in lectures and support in-class. Deviation from this list requires explicit instructor permission (typically an email thread that you include in your project documentation).
2. Your application needs to include at least one client and one service, that work together to provide functionality.
   • Your client can be an Android or a Desktop application (macOS, Windows or Linux). (Building a web client or iOS client requires instructor permission).
   • Your service should be a web service that processes client requests: typically this means storing, processing and returning data that is required by the client applcation. Optionally, you may find that your application needs multiple services (e.g. fetching data from an existing service, and storing data on a second service that you create).; this will vary based on the needs of your particular problem.
3. Your client application must adhere to the conventions of that platform.
   • Desktop applications should support min/max/resizing; user functions should be clear and easy to find and use (through menus, toolbars, keyboard shortcuts); standard features like copy/paste, undo/redo should be implemented.
   • Mobile applications should use conventions for that platform: touch for selection, other gestures as appropriate; popup menus or hamburger buttons that expand to list functionality and so on.
4. Your application must save and restore data between sessions. This typically means saving user preferences for the client on the local filesystem (e.g. window position and size), and shared data in database on your remote service (e.g. for a notes application, notes would reside in some database so that they were not lost if you rebooted the system).
5. All other functional requirements are to be determined by you and your team. A significant portion of your final grade will be based on (a) how well you solve the problem for your user, and (b) how well your design “fits” the target platform. You are expected to propose (and design and implement) additional features to meet the needs of your users and the problem you are attempting to solve.
6. You will be required to submit a proposal early in the course, describing your proposed features, and get feedback/approval for a custom specification before you can proceed with implementation.

Suggested projects

Create your own project

Alteratively, you and your team are free to choose your own project topic. As a starting point you should:

1. Review the project requirements above! You are required to meet these in all cases.
2. Identify target users. Make sure that you are solving a a real problem for them. The interview process can help you define problems and areas to investigate.
3. Identify the purpose of your application. e.g. devise a better way to store code snippets for a developer; build a e-book reader that stores books and user ratings; a system for UW students to plan courses using UW Open API data.
4. Determine the basic requirements and features that would be required to address this problem. Look at competing products to get ideas. Brainstorm with your team and try to be original in solving the problem in a unique and better way!
5. Identify local and remote functionality - make sure that you are dividing features across both a client and service.

How these requirements contribute to your grade

Your grade will be based on your progress through the term.

• Did you make progress at each step of your project? Did you and your team work effectively together?
• How well you meet these requirements. Did you complete everything described above?
• How well designed your application is. Did you ensure that you built a compelling, useful and usable application? Did you take short-cuts?
• Did you go beyond the bare-minimum requirements? e.g. adding a second client, or expanding the requirements.
• How complex is the problem that you were attempting to solve? Was this a challenge for you and your team?
• Did you follow the prescribed process, including design, testing, and deployment?

GitLab Project

As part of your project activities, you will be creating project documents and other artifacts and storing these in a a GitLab project. This project should contain everything related to your project! This includes your project proposal, design documents, meeting minutes from your sprints, software releases that you produce and any other documentation that is required.

1/ Project Setup

Your GitLab project must be setup as described in the Getting Started section, and should minimally include:

• A project landing page (aka README, see below).
• All related documentation and source code (see below).
• Release pages for each sprint (see below).
• Milestones corresponding to each sprint.
• Issue lists for each sprint, including issues closed as part of that sprint.
• Unassigned issues representing incomplete work.

2/ Documentation

2.1. README (Project Landing Page)

You should have a markdown file in the root of your source code repository named README.md. This will serve as a landing-page for your project (i.e. its the first thing that users will see when visiting your project page!). It should contain the following sections.

# SUPER-COOL-PROJECT-NAME

## Goal
A brief description of your project. What is it? What does it do?

## Team Members
List each person's name and email address.

## Screenshots/Videos
Optional, but often helpful to have a screenshot or demo-video for new users.

## Quick-Start Instructions
Instructions. Details on how to install and launch your application. 

## Project Documents
Include a link to your Wiki pages, see below.

## Software Releases
Include a link to your Wiki pages, see below.

2.2. Wiki

Your GitLab project has a built-in Wiki, where you can store more complex documents and project executables. It should contain the following documents:

• Project proposal
• Meeting minutes
• Everything else mentioned in the final submission rubric

3/ Software Releases

Each sprint should produce an installable and runnable version of your project, which should contain the features that were completed during the sprint. The output from a sprint should be a release-quality build of your product, which you will store in this section of your project repository.

Your README.md file (from above) should include links to the components of each software release. Your software release should include:

• Release notes: a markdown or text file, containing at least:

  • the release date (which should be the sprint demo date)
  • the version of this release (which you increment for each release)
  • a list of changes that were included.

• Installers: this is a packaged version of your application that a user could use to install your software. You should support and test installation on at least 2 platforms (pick two from Linux, Windows, macOS - whatever you have available for testing).

  Acceptable forms of packaging include:

  • a zip or tar file that, when extracted, contains bin/ and lib/ directories, and a script that launches the application.
  • an exe, dmg or pkg file that, when executed, installs the application.

4/ Source Code Repository

Source code and other assets required to build your application should be stored in your project’s source code repository. The structure should look something like this by the end of the term.

.
├── .gitignore
├── .gitlab-ci.yml
├── LICENSE.txt
├── README.md
├── application
│   ├── build.gradle
│   └── src
│       ├── main
│       │   ├── java
│       │   └── kotlin
│       └── test
│           └── java
├── buildSrc
│   ├── build.gradle
│   └── src
│       └── main
│           └── groovy
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── releases
│   └── v0.1-release-notes.md
│   └── v0.1-installer.dmg
│   └── v0.1-installer.exe
│   └── v0.2-release-notes.md
│   └── v0.2-installer.dmg
│   └── v0.2-installer.exe
├── server
│   ├── build.gradle
│   ├── gradle.properties
│   └── src
│       ├── main
│       │   ├── java
│       │   ├── kotlin
│       │   └── resources
│       └── test
│           └── kotlin
├── settings.gradle
└── shared
    ├── build.gradle
    └── src
        └── main
            ├── java
            └── kotlin

Most of your repository contains the source code and related documents for your project. It is recommended that you follow the structure provided above, which will build properly in GitLab CI/CD.

Final Submission

There is also a final submission due at the end-of-term (see assessment).

Guidelines

• Everything related to your project, and this final submission, must be included in your GitLab project. We will ignore content posted anywhere else.
• We will read your documentation, install and run your application. We will also review your source code (from the main branch only) and all submission details.
• Everyone on the team will receive the same grade for this component.

What to include

README.md

You should have a README file, as described in previous sections. This is your landing page for your project.

Main Sections

You should have documentation including these sections. Each section should be documented in your Wiki and linked from the README file. These can be separate pages, or a single page with sections - your choice on formatting and structure.

• Project: Name of your project, list of team members, overview of the project goals.
• Meeting Minutes: From your meetings during the term.
• Requirements: A description of the problem that you are attempting to solve, and your target users. A brief description of the major features of your project (do not naively link to an issues list, but describe the features for your users).
• Design: Class diagrams for your data models; architecture diagram. Discussion of any significant design decisions that were made (e.g. design patterns used, architectural style, how data flows). What technical decisions did you make that were beneficial? What technical decisions didn’t work out as well?
• Discusssion: What best-practices were used. What worked well for your team? What would you do differently? If there were features that were not completed, discuss what happened and what you learned from it.

Installation Details

• Instructions: links to your latest release, and installation instructions for both the client and service (if needed).
• Software releases: link to each release page, including installers for both client and service.
  • You should have an installer for the client, and some way for us to run your service e.g. hosted in the cloud already, or runnable from a Docker image. Make sure to include instructions on how to install and execute everything!

Source Code

The complete source code to build your project should be committed.

• All features committed to main branch, and your project builds properly from main.
• Your issues list should align with your source code (i.e. closed issues are implemented, open issues were not merged to main).
• You should include unit tests for major features and these should pass properly.

Gallery

Here’s a gallery of some projects that were created in past offerings of this course. Teams have a lot of leeway in choosing what to design and build, so each project is unique! Screenshots and videos are posted here with the author’s permission.

Editors

Inkwell, a rich-text note-taking application. Copyright (c) 2023 Benjamin Du, Yuying Li, Charles Shen, and Andy Yang.

Zircon, a markdown editor with syntax highlighting. Copyright (c) 2023 Eddy Guo, Joshua Johnson, Mihran Mashhud, Tony Tascioglu, and Mrugank Upadhyay.

Notes, an app for organizing short notes. Copyright (c) 2023 Hoang Dang, Inseo Kim, Guransh Khurana, Abhay Menon, Anshul Ruhil.

Real-Time Collaboration

Whiteboard, a collaborative drawing space. Copyright (c) 2023 Terry Zheng, Jonathan Wang, Seth Hammell, and Alan Lee.

Whiteboard, a collaborative space with real-time synchronization. Copyright (c) 2023. Anh Huy Nguyen Do, Chirag Jindal, Mayank Devesh Shrivastava, Pranav Sai Vadrevu. (video)

Whiteboard, a collaborative drawing space. Copyright (c) 2023. Kevin Chen, Franklin Gao, Catherine Tao, Andrew Zhang. (video)

Forming Teams

You are expected to form project teams in the first week of the course¹.

• Teams should consist of four people.
• You all must be enrolled in the same sections of the course.
• You must all attend in-person (i.e. this course cannot be taken “online”)

How do you find team members?

• Join friends who are taking the course! If you are in different sections, ask the instructor, and they may be able to move you all into the same section.
• Post in the course forums: we will have a forum thread where you can introduce yourself.
• If you’re in-class, introduce yourself to people sitting near you.

Once you have a team formed, please email the instructor with details:

• Section number.
• Names and email addresses of your team members.
• The URL to your GitLab project.

Project Proposal

In the first few weeks, you and your team will choose a project, define requirements, and discuss design issues.

You should create a Wiki page in your GitLab project named Project Proposal, and link to it from the landing page of your project site (i.e. the top-level README file at the top of your project). This page should contain the following details, either on a single page, or multiple pages linked together.

(a) Project Plan

As discussed in the Planning slides, you should identify and detail:

• Goals: What high-level project goals do you have?
• Resources: How is your project staffed? Do you have any constraints on people’s time and availability?
• Risks: What project risks can you identify? How will you mitigate these?
• Milestones: Identify your sprints and deadlines (dates provided on the schedule), and a high-level plan of what to focus on for each sprint.

(b) Requirements

As discusssed in the Requirements slides, you should detail:

• Problem: One or two-sentence summary of your project idea. What problem are you attempting to solve?
• Users: The specific group of users that would be interested in your project
  • Interview at least 2 people in that group, and summarize their feedback in your requirements.
  • (Optional) Include a role-based or goal-based persona suitable for your project.
• Functional Requirements: What features are you considering?
  • List your “top-ten” requirements: what features do you think are critical? This list doesn’t need to be comprehensive but should call out features that are core to your project.
  • Describe in a document but also link to your issues list in GitLab (i.e. Product Backlog of unassigned issues).

(c) Design

As discussed in the Architecture and Design slides, you should detail:

• System Diagram: A box-and-lines diagram that shows the architecture of your application (aka architectural style).
• Non-Functional Requirements: If applicable to your project, list any non-functional requirements (system qualities related to performance, or other factors). Most projects in this course will not have these, unless specifically identified by a user during interviews.

Sprints & Demos

Most of the term will be spent iterating on your project. Sprints start after the project proposal. You will be working in two-week iterations, called sprints. Over a two-week period, you will have a kickoff meeting, do some work, and finally demo that work to the TA.

Day 1: Kickoff

The first day is the official kickoff, where your team collectively decides what you want to include in the sprint. Your primary task in this meeting is to choose items from the Product Backlog and assign them.

Here’s some suggestions to help you determine what to do during the sprint.

• Address feedback from the previous sprint’s demo. You may have received feedback from the previous sprint. Treat suggestions from course staff as important - they represent your customers!
• Address high-risk items early. This gives you time to pivot if needed, and also helps prevents you from investing too much time in a path that ultimately won’t work.
• Look for blocking issues: items that are critical for other systems. Examples of this might be the class structure for business objects (e.g. data classes) that are used by other features.
• Do NOT assign more work than you think you can do.

Outcomes from this meeting:

• You should have issues logged and assigned to the team, representing the work for this sprint.
• You should have meeting minutes documenting who was present, and any major decisions made by the team during the meeting.

Day 2/3: Standup

These are “working days” where your team gets together and does the actual work towards the sprint’s goals. You are expected to work in-class together; the instructor and TAs will be available to help you out.

You should have meeting minutes documenting who was present each time you meet, and any issues that you encounter.

Day 4: Demo

The last day of a sprint is demo to the course staff of what you’ve accomplished during the sprint. This is a checkpoint of sorts, where we can provide feedback and make suggestions.

This is what you should have completed before the demo:

• You should have recorded meeting minutes for every team meeting prior to the demo.
• The issues for the sprint should be updated
  • Completed issues should be closed in GitLab with details on what was done.
  • Code changes need to be committed and merged back to the main branch.
  • You should have unit tests that cover the features that you have completed.
• You should also have readied a software release which details what you accomplished and has a link to an installer.

What does the demo look like?

• Your demo will be informal and last about 10 minutes.
• Using an INSTALLED version of the application, demo each completed feature, and answer any questions. (Your issues list in GitLab is a great way to drive this discussion).
• The person who developed the feature should demo it.
• All demos need to be run from the same machine.

Outcomes from this meeting:

• The TA will assign a mark and your grade will be returned the week after the demo.
  • See assessment for marking guidelines.

Technologies

The following technologies are used in this course. See the setup toolchain for instructions on setting up these tools.

Required Technologies

Programming Languages & SDKs

• Kotlin is the primary language used.
• Java JDK is required for both desktop and Android.
• Android SDK if you are developing an Android application.

Libraries

• JUnit for unit testing.
• Compose for building user interfaces.
• Ktor for networking and building a web service.

Tools

• Gradle for managing builds.
• Git for managing source code.
• IntelliJ IDEA for editing/debugging code (optional).
• Android Studio for editing/debugging Android code (optional).
• Docker to create a service image.

Compatibility

It’s important to use matching versions of each of these libraries. The following version combinations are supported.

• Java JDK is the JDK that you need to install in IntelliJ (typically both on your JAVA_PATH and in your project settings).
• Compiling w. Gradle means that Gradle supports compiling with this version of the JDK.
• Running Gradle means that Gradle can bootstrap itself with this version.
• Kotlin Compiler, Compose and Ktor are the library versions specified in your project setup (e.g. `gradle.properties).

Setup Toolchain

We will be building Kotlin applications and services, and using the Java JDK as our deployment target. This means that you need to install the Java JDK and the Kotlin compiler on your development machine. It’s also highly recommended that you install the Intelli IDEA IDE for working with Kotlin, as it offers advanced language support and integrated well with our other tools and libraries¹.

Check the technologies page for the recommended version numbers. Also, make sure that you and your team all install the same distribution and versions of these tools!

The following represents the minimum toolchain for the course.

Git

We use Git for version control, so you will need Git installed to perform operations on your source code.

Git is pre-installed on macOS and Linux; Windows users can install it from https://git-scm.org. Once it’s installed, you may need to update your path to include the Git installation directory. You can check your installation using the git version command.

❯ git version
git version 2.39.3 (Apple Git-145)

Java JDK

• Download and install the JDK from Azul or OpenJDK (make sure to match your system architecture).
• Add JAVA_HOME to your system’s environment variables, pointing to this installation.
• Update your path to include the directory containing the Java executables.

For example, I am using JDK 18 (at the time I’m writing this). I have the following lines in my .zshrc:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
export PATH=$PATH:$JAVA_HOME/bin

You can check your installation using the java version command. Make sure the version matches what you expected to see.

$ java -version
openjdk version "17.0.8.1" 2023-08-24 LTS
OpenJDK Runtime Environment Zulu17.44+53-CA (build 17.0.8.1+1-LTS)
OpenJDK 64-Bit Server VM Zulu17.44+53-CA (build 17.0.8.1+1-LTS, mixed mode, sharing)

IntelliJ IDEA

IntelliJ IDEA is our recommended development environment. You can install it from https://www.jetbrains.com/idea/download/.

There is an Open Source Community version which will work for this course. There is also an Ultimate license, which includes better support for databases, web services and other frameworks that we’ll be using. This is normally a paid upgrade, but as a student you can get a free license² to most of thier products, including this version of IntelliJ IDEA.

You can check the installed version by opening IntelliJ IDEA and looking at the IntelliJ IDEA - About dialog.

Kotlin

We will need a Kotlin compiler, and the Kotlin standard libraries. IntelliJ IDEA includes a Kotlin plugin, so if you have installed IntelliJ IDEA and you are working from the IDE, then you do not need to install Kotlin.

However, if you wish to compile from the command-line, or use a different editor, then you will need to install Kotlin manually. It can be installed from https://www.kotlinlang.org or from most package managers (e.g. brew install kotlin if you are a Mac user with Homebrew installed).

If you install the command-line version, you can check your installation using the kotlin -version command.

❯ kotlinc -version
info: kotlinc-jvm 1.9.10 (JRE 17.0.8.1+1-LTS)

Create a Project

You should create a single source tree, with subprojects for each major deliverables. e.g. an application project (for desktop), a server project (for your service) and models (for model classes that are shared between projects).

This ultimately needs to be setup in a project structure that looks like this:

cs346-project/
├── application/
├── gradle/
├── gradle.properties
├── gradlew
├── gradlew.bat
├── models/
├── readme.md
├── server/
└── settings.gradle.kts

application, server and shared all represent projects, with their own configuration files.

• application is a Compose desktop project.
• server is a Ktor project.
• models are shared data model classes that each of the other projects use.

How to create the top-level project

Use the File-New Project wizard in IntelliJ to create a new Empty project. This will give you a top-level project with settings.gradle.kts, gradle/ directory and so on. Make sure to pick the correct version of JDK based on the Compatibility table.

Move the application code into an application project:

1. Create a directory named application.
2. Move the build.gradle.kts and src folder into the application directory.
3. Edit the top-level settings.gradle.kts and add the following line to the bottom of the file:

include("application")

This produces the following directory structure:

.
├── application
│   ├── build.gradle.kts
│   └── src
│       ├── main
│       └── test
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradle.properties
├── gradlew
├── gradlew.bat
└── settings.gradle.kts

Typing ./gradlew build at the top-level should build the project.

Next we’ll add the other missing projects: server and models.

Adding the remaining projects

The trick to adding more projects is:

• Create the type of project using the IntelliJ IDEA Project Wizard for the type of project that you want.
• Place it in a subdirectory from your main project. Each project directory should just contain the generated src directory, and the build.gradle.kts file. You don’t want anything else in the project subdirectory.
• Finally update the settings.gradle.kts to add each project to the include statement.

include("application", "console", "shared")

Gradle Template

Here are sample configuration files for a multi-project Gradle build. It has the following structure:

project-template/
├── application/
├── build
├── console/
├── gradle/
├── gradle.properties
├── gradlew
├── gradlew.bat
├── models/
├── readme.md
└── settings.gradle.kts

application, console and shared all represent projects, with their own configuration files.

Top-Level (Root)

The project root contains the settings.gradle.kts file, which defines the overall project structure.

pluginManagement {
    repositories {
        gradlePluginPortal()
        maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
    }

    plugins {
        kotlin("jvm").version(extra["kotlin_version"] as String)
        id("org.jetbrains.compose").version(extra["compose_version"] as String)
    }
}

rootProject.name = "notes-application"
include("application", "console", "shared")

It also contains gradle.properties, which includes project definitions and version numbers (which are referenced by the settings.gradle.kts.

org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
kotlin.code.style=official
kotlin_version=1.9.10
compose_version=1.5.1
ktor_version=2.3.5
logback_version=1.4.11

Gradle wrapper settings

There is a top-level gradle directory, containing the Gradle bootstrap files (the means by which Gradle downloads and installs itself when you run gradlew). These files are auto-generated by Gradle when you setup the project.

You might want to update the gradle-wrapper.properties to point to a recent version fo Gradle by changing the distributionURL line. In this example, we’re specifying Gradle 7.5.1.

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Application project

The Application project contains a single src folder, containing the directory tree, and a single build.gradle.kts file which includes the configuration for this specific project. This is a Compose application, so we should expect to see application-style plugins and dependencies.

import org.jetbrains.compose.desktop.application.dsl.TargetFormat

plugins {
    kotlin("jvm")
    id("org.jetbrains.compose")
}

group = "net.codebot"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
    maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
    google()
}

dependencies {
    // Note, if you develop a library, you should use compose.desktop.common.
    // compose.desktop.currentOs should be used in launcher-sourceSet
    // (in a separate module for demo project and in testMain).
    // With compose.desktop.common you will also lose @Preview functionality
    implementation(compose.desktop.currentOs)
    implementation(project(":models"))
}

compose.desktop {
    application {
        mainClass = "net.codebot.desktop.MainKt"

        nativeDistributions {
            includeAllModules = true
            targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
            packageName = "client"
            packageVersion = "1.0.0"
        }
    }
}

Console project

The Console project has a similar structure to the Application project, with a single src folder and a build.gradle.kts file for this project. This is a console application so it doesn’t need Compose support.

plugins {
    kotlin("jvm")
    application
}

group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    implementation(project(":models"))
    testImplementation(kotlin("test"))
}

tasks.test {
    useJUnitPlatform()
}

kotlin {
    jvmToolchain(8)
}

application {
    mainClass.set("net.codebot.console.MainKt")
}

Models project

Finally, the Models project provides services to both the Application and Console projects. It’s basically a library - not something that we execute directly, but code that we need to pull into the other projects. We keep it in a shared project to avoid code duplication.

Here’s the relevant build.gradle.kts.

plugins {
    kotlin("jvm")
    kotlin("plugin.serialization") version "1.9.10"
}

group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.5.1")
    testImplementation(kotlin("test"))
}

tasks.test {
    useJUnitPlatform()
}

kotlin {
    jvmToolchain(8)
}