Feat: Add ADR Template, Generator, and First Example (#24)

* feat: add ADRs readme

* feat: adr generator

* docs: initial ADR

* refator: readability

* chore: lint

* feat: add ADRs readme

* feat: adr generator

* docs: initial ADR

* refator: readability

* chore: lint

Author: sean-dickinson

docs/adrs/0001_use_separate_model_and_authentication_for_students.md

@@ -0,0 +1,29 @@
+# 0001. Use Separate Model And Authentication For Students
+
+Date: 2026-05-09
+
+## Authors
+
+- Sean Dickinson
+
+## Context
+
+Students are a very different type of user compared to administrators. Some students using the application may have low reading comprehension and struggle with basic typing skills. 
+They also may not all have email addresses and be able to remember passwords.
+
+The goal is to make the student login process as simple and frictionless as possible. There is no real need for security, as the application does not contain any sensitive information tied to students.
+There also is no incentive for a student to login as another student, as they can only earn rewards via their actions in the application. 
+There are no actions they take in the application would cause the logged in account to lose rewards or cause any negative consequences for another student.
+
+## Decision
+- We will create a separate model for students, and use a simple authentication system that does not require email addresses or passwords.
+- The students will be provided a unique link to the login page for their class, and will be able to select their name from a list of students in their class to log in.
+- From the perspective of the application, students will be a separate type of user with their own authentication system, and will not be able to access any of the administrator features or data.
+- Students will have their own session model and authentication concern that is separate from the administrator session model and authentication concern so there is no risk of students being able to access administrator features.
+- We will use Rails' built-in authentication scaffold for the administrator authentication system
+- We will use a modified version of the Rails' built-in authentication scaffold for the student authentication system that is tailored to the needs of students.
+
+## Consequences
+
+- This approach allows us to provide a simple and user-friendly login experience for students, while still maintaining a clear separation between students and administrators in the application.
+- We will have to maintain and support 2 separate authentication systems and sets of models

docs/adrs/README.md

@@ -0,0 +1,31 @@
+# Architecture Decision Records (ADRs) 
+
+## Purpose
+ADRs are a way to document the architectural decisions made during the development of a software project. 
+They provide a clear and concise record of the reasoning behind each decision, making it easier for future developers to understand the context and rationale behind the choices made.
+A good ADR provides a clear "why" regarding a decision around the architecture of the system, especially when the decision is not obvious.
+
+
+## Creating a New ADR
+
+Use the built-in Rails generator to create a new ADR with the correct filename and template pre-filled:
+
+```sh
+bin/rails generate adr <title_in_snake_case>
+```
+
+For example:
+
+```sh
+bin/rails generate adr use_postgres_as_primary_database
+```
+
+This will create `docs/adrs/0001_use_postgres_as_primary_database.md` with today's date and all required sections. The number is assigned automatically based on existing ADRs. The title is normalized to snake_case regardless of how it's provided — kebab-case, CamelCase, and spaces all work.
+
+## Format
+Each ADR should follow a consistent format to ensure clarity and ease of understanding. A common format includes the following sections:
+1. **Title**: A brief and descriptive title for the decision.
+2. **Context**: A description of the problem or situation that led to the need for a decision.
+3. **Authors**: The name of the person(s) or team responsible for making the decision.
+4. **Decision**: A clear statement of the decision that was made.
+5. **Consequences**: An explanation of the consequences of the decision, including any trade-offs or implications.

lib/generators/adr/adr_generator.rb

@@ -0,0 +1,21 @@
+class AdrGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+
+  def create_adr_file
+    template "adr.md.erb", adr_path
+  end
+
+  private
+
+  def adr_path
+    "docs/adrs/#{next_number}_#{name.underscore.parameterize(separator: "_")}.md"
+  end
+
+  def next_number
+    @next_number ||= begin
+      highest_existing_adr = Dir.glob(File.join(destination_root, "docs/adrs/[0-9]*.md")).last
+      highest_existing_number = highest_existing_adr ? File.basename(highest_existing_adr).to_i : 0
+      format("%04d", highest_existing_number + 1)
+    end
+  end
+end

lib/generators/adr/templates/adr.md.erb

@@ -0,0 +1,19 @@
+# <%= next_number %>. <%= human_name.titleize %>
+
+Date: <%= Time.now.strftime("%Y-%m-%d") %>
+
+## Authors
+
+-
+
+## Context
+
+<!-- Describe the problem or situation that led to this decision. What forces are at play? -->
+
+## Decision
+
+<!-- State the decision clearly. "We will..." -->
+
+## Consequences
+
+<!-- What becomes easier or harder as a result of this decision? Include trade-offs. -->

test/generators/adr_generator_test.rb

@@ -0,0 +1,57 @@
+require "test_helper"
+require "rails/generators/testing/behavior"
+require "rails/generators/testing/assertions"
+require "generators/adr/adr_generator"
+
+class ADRGeneratorTest < Rails::Generators::TestCase
+  tests AdrGenerator
+  destination Rails.root.join("tmp/generator_tests")
+  setup :prepare_destination
+
+  test "creates adr file with sequential number" do
+    run_generator [ "use_postgres_as_primary_database" ]
+    assert_file "docs/adrs/0001_use_postgres_as_primary_database.md"
+  end
+
+  test "normalizes kebab-case input" do
+    run_generator [ "use-postgres-as-primary-database" ]
+    assert_file "docs/adrs/0001_use_postgres_as_primary_database.md"
+  end
+
+  test "normalizes CamelCase input" do
+    run_generator [ "UsePostgresAsPrimaryDatabase" ]
+    assert_file "docs/adrs/0001_use_postgres_as_primary_database.md"
+  end
+
+  test "normalizes spaces input" do
+    run_generator [ "Use Postgres As Primary Database" ]
+    assert_file "docs/adrs/0001_use_postgres_as_primary_database.md"
+  end
+
+  test "increments number based on existing adrs" do
+    FileUtils.mkdir_p(File.join(destination_root, "docs/adrs"))
+    FileUtils.touch(File.join(destination_root, "docs/adrs/0001_existing_decision.md"))
+    run_generator [ "second_decision" ]
+    assert_file "docs/adrs/0002_second_decision.md"
+  end
+
+  test "populates template with title and date" do
+    run_generator [ "use_postgres_as_primary_database" ]
+    assert_file "docs/adrs/0001_use_postgres_as_primary_database.md" do |content|
+      assert_match "# 0001. Use Postgres As Primary Database", content
+      assert_match Date.today.strftime("%Y-%m-%d"), content
+      assert_match "## Context", content
+      assert_match "## Decision", content
+      assert_match "## Consequences", content
+    end
+  end
+
+  test "title number matches filename number" do
+    FileUtils.mkdir_p(File.join(destination_root, "docs/adrs"))
+    FileUtils.touch(File.join(destination_root, "docs/adrs/0001_existing_decision.md"))
+    run_generator [ "second_decision" ]
+    assert_file "docs/adrs/0002_second_decision.md" do |content|
+      assert_match "# 0002.", content
+    end
+  end
+end