From 4efe4f0f64d9f51e7e77a23aa91513635dc1b1cf Mon Sep 17 00:00:00 2001
From: Andrew <Quark>
Date: Sat, 11 Jul 2026 11:57:26 -0400
Subject: [PATCH] Init design doc

---
 .../patchats/api/matches/design.md            | 73 +++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 src/main/java/org/patinanetwork/patchats/api/matches/design.md

diff --git a/src/main/java/org/patinanetwork/patchats/api/matches/design.md b/src/main/java/org/patinanetwork/patchats/api/matches/design.md
new file mode 100644
index 0000000..fe6a73f
--- /dev/null
+++ b/src/main/java/org/patinanetwork/patchats/api/matches/design.md
@@ -0,0 +1,73 @@
+### Overview
+
+ - This API lists matches from database
+
+### Endpoints
+
+| Method | Path | Description | 
+|--------|------|-------------|
+| GET | /api/matches/{year} | List pairings by year |
+| GET | /api/matches/{year}/{month} | List pairings by month |
+| GET | /api/matches/member/{id} | List pairings by member id |
+
+
+  Response: `ApiResponder<Match[]>`
+  ```typescript
+  interface Match {
+      match_id: string     // UUID
+      member_a_id: string  // UUID
+      member_b_id: string  // UUID
+      month: string        // YYYY-MM, from match_cycles.run_at
+      status: string
+  }
+  ```
+* Figured a flat list is more flexible for rendering instead of grouping by month server side
+
+## /api/matches/{year}
+* Join on match_cycles, filtered by run_at within year
+```sql
+   SELECT m.id, m.member_a_id, m.member_b_id, m.status,
+          to_char(c.run_at, 'YYYY-MM') AS month
+   FROM matches m
+   JOIN match_cycles c ON m.cycle_id = c.id
+   WHERE c.run_at >= TIMESTAMPTZ '2026-01-01'
+     AND c.run_at <  TIMESTAMPTZ '2027-01-01';
+ ```
+ 
+## /api/matches/{year}/{month}
+* Join on match_cycles, filtered by run_at within month
+```sql
+   SELECT m.id, m.member_a_id, m.member_b_id, m.status,
+          to_char(c.run_at, 'YYYY-MM') AS month
+   FROM matches m
+   JOIN match_cycles c ON m.cycle_id = c.id
+   WHERE c.run_at >= TIMESTAMPTZ '2026-01-01'
+     AND c.run_at <  TIMESTAMPTZ '2026-02-01';
+```
+
+## /api/matches/member/{id}
+* Filter matches by member id
+```sql
+   SELECT m.id, m.member_a_id, m.member_b_id, m.status,
+          to_char(c.run_at, 'YYYY-MM') AS month
+   FROM matches m
+   JOIN match_cycles c ON m.cycle_id = c.id
+   WHERE m.member_a_id = :id
+     OR  m.member_b_id = :id
+```
+
+### Layering
+
+Controller: 
+- `MatchController` (`/api/matches`)
+    * `listByYear(year)`
+    * `listByMonth(year, month)`
+    * `listByMember(id)`
+
+Repository: `MatchRepository` (Spring JDBC, `NamedParameterJdbcTemplate`)
+- owns the SQL above; returns `List<Match>`
+
+DTO: `Match` (interface Match)
+- `ApiResponder<List<Match>>`
+
+