Skip to content

Commit a76fd68

Browse files
ArchILLtectArchILLtect
committed
feat(docs): add ASAP task list and journals index for Week 3 planning
1 parent 28dfb06 commit a76fd68

8 files changed

+593
-350
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
![Backend CI](https://github.com/ArchILLtect/sameboat-backend/actions/workflows/backend-ci.yml/badge.svg)
22
# SameBoat Backend (Spring Boot + Java 21)
33

4-
> Quick Links: [Instructions (setup & migrations)](./docs/instructions.md) | [API Reference](./docs/api.md)
4+
> Quick Links: [Instructions (setup & migrations)](./docs/instructions.md) | [API Reference](./docs/api.md) | [Week 3 Plan](./docs/Weekly%20Plan%20Docs/week_3_plan_same_boat_honors_project_fall_2025.md) | Journals: [Index](./docs/journals/README.md) · [Week 1](./docs/journals/Week1-Journal.md) · [Week 2](./docs/journals/Week2-Journal.md)
55
66
## Run locally
77
1. Copy `.env.example` → `.env` and fill appropriate JDBC DS values (or rely on defaults in `application.yml`).

‎docs/ASAP.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# ASAP Task List
2+
3+
Purpose: High-priority items to unblock momentum immediately at the start of Week 3. Keep this file short-lived (archive after completion into journal or close as a PR).
4+
5+
---
6+
## 1. Finish Week 2 Frontend Tasks
7+
**Goal:** Minimal end‑to‑end auth UX (login -> /me -> logout -> redirect on 401) plus basic profile display.
8+
9+
| Subtask | Status | Priority | Notes / Next Action |
10+
|---------|--------|----------|----------------------|
11+
| Implement login form (email + password) | ☐ | P0 | POST /auth/login; show BAD_CREDENTIALS message |
12+
| Persist session via cookie automatically | ☐ | P0 | Browser handles; ensure fetch uses `credentials: 'include'` |
13+
| Global fetch wrapper w/ 401 handling | ☐ | P0 | Redirect to /login on UNAUTHENTICATED or SESSION_EXPIRED |
14+
| /me fetch on app mount (AuthProvider) | ☐ | P0 | Set user context; null if 401 |
15+
| Display user email/avatar placeholder | ☐ | P1 | Simple component (ProfileBadge) |
16+
| Logout button (POST /auth/logout) | ☐ | P1 | Clear UI state after 204 |
17+
| Patch profile (optional this sprint) | ☐ | P2 | Only if time; update displayName & bio |
18+
| Add MSW mocks for auth endpoints | ☐ | P1 | Mirror backend codes: BAD_CREDENTIALS, UNAUTHENTICATED, SESSION_EXPIRED |
19+
| Vitest tests: login success & 401 redirect | ☐ | P1 | Cover redirect logic + context update |
20+
| Coverage report (baseline) | ☐ | P2 | Document %; gate can come later |
21+
22+
**Definition of Done (Frontend slice):** User can login, see their email, refresh retains session, expired session triggers redirect, logout returns to login screen.
23+
24+
---
25+
## 2. Fix / Enhance Backend CI
26+
**Goal:** Strengthen pipeline fidelity & transparency. Current CI green but missing schema + stronger coverage signal.
27+
28+
| Subtask | Status | Priority | Notes / Next Action |
29+
|---------|--------|----------|----------------------|
30+
| Add Testcontainers Postgres to main `verify` job | ☐ | P0 | Re-run migrations against real PG; adapt memory/timeouts |
31+
| Keep fast H2 job (matrix) for quick feedback | ☐ | P2 | Parallel speed vs fidelity balance |
32+
| Integrate migration immutability script (already) – enforce fail-fast | ☑ | Done | Present; ensure docs reference remains |
33+
| Promote migration profile to default (or separate job) | ☐ | P1 | Possibly `verify -Pwith-migration-test` in second job |
34+
| Publish JaCoCo report artifact | ☐ | P1 | Upload HTML for PR inspection |
35+
| Add coverage XML + PR comment (optional) | ☐ | P2 | Use action (e.g. codecov or custom) |
36+
| Raise coverage gate to 75% after new unit tests | ☐ | P1 | Only after added tests pass locally |
37+
| Add caching for Maven & Testcontainers layers | ☐ | P2 | Optimize build time |
38+
| Add CI badge for coverage (shields.io manual) | ☐ | P3 | After stable coverage baseline |
39+
| Lint / format check (Spotless or Checkstyle) | ☐ | P3 | Future quality gate |
40+
41+
**Definition of Done (CI enhancement):** Main pipeline runs Postgres-backed migration & integration test job + coverage artifact; gate reflects intended minimum.
42+
43+
---
44+
## 3. Add JavaDocs for New / Updated Classes
45+
**Goal:** Provide concise, high-value documentation for maintainability & onboarding.
46+
47+
| Class / File | Status | Priority | Required Doc Elements |
48+
|--------------|--------|----------|-----------------------|
49+
| `AuthController` | ☐ | P0 | Purpose, endpoints summary, error codes mapping |
50+
| `SecurityConfig` | ☐ | P0 | Filter chain ordering, public vs protected endpoints |
51+
| `SessionAuthenticationFilter` | ☐ | P0 | Cookie extraction, expiry handling, context population |
52+
| `SameboatProperties` | ☐ | P0 | Property groups (auth, cookie, session, cors) |
53+
| `UserService` (new methods) | ☐ | P1 | Registration, normalization, hashing rationale |
54+
| `SessionService` (if present) | ☐ | P1 | Touch semantics, expiry strategy |
55+
| `UserController` (updated responses) | ☐ | P1 | Auth codes & validation errors |
56+
| DTOs: `RegisterRequest`, `LoginRequest`, `LoginResponse`, `UpdateUserRequest` | ☐ | P2 | Field intent, validation rules |
57+
| `ExpiredSessionIntegrationTest` | ☐ | P2 | Test purpose & scenario coverage |
58+
| `RegistrationIntegrationTest` | ☐ | P2 | Cases covered (duplicate, wrong password) |
59+
| `BadCookieIntegrationTest` | ☐ | P3 | Distinguish UNAUTHENTICATED vs BAD_CREDENTIALS |
60+
| `CorsConfig` | ☐ | P2 | Origins list binding & credentials rationale |
61+
| `UserEntity` (passwordHash note) | ☐ | P1 | Persistence constraints, lifecycle callbacks |
62+
63+
### JavaDoc Style Guidelines
64+
- Start with a one-line summary sentence.
65+
- Include rationale if behavior differs from standard Spring conventions.
66+
- Reference error codes (`UNAUTHENTICATED`, `BAD_CREDENTIALS`, etc.) where relevant.
67+
- Avoid repeating self-evident field names; focus on intent & constraints.
68+
69+
### Suggested Workflow
70+
1. Add JavaDocs to highest priority classes (controllers, security, filter, properties).
71+
2. Run `mvn -DskipTests javadoc:javadoc` to validate formatting.
72+
3. Follow with service / entity / DTOs.
73+
4. Mark table status as completed (☑) and remove table once all P0/P1 done.
74+
75+
---
76+
## 4. Quick Win Order of Execution
77+
1. Add password complexity + unit test (backend) to unblock frontend expectation of error message structure.
78+
2. Implement frontend login flow & 401 redirect before rate limiting (ensures base path works).
79+
3. Integrate Testcontainers migration test into CI for realism.
80+
4. Add rate limiting + `RATE_LIMITED` error code & test.
81+
5. Add pruning scheduler & test (in-memory clock or manual expiry manipulation).
82+
6. JavaDocs pass P0 classes.
83+
7. Raise coverage gate after new unit tests.
84+
85+
---
86+
## 5. Blocking Issues / Questions (Fill In)
87+
| Issue | Impact | Owner | Resolution Target |
88+
|-------|--------|-------|-------------------|
89+
| (example) Need decision: use Bucket4j vs simple Atomic counters | Could delay rate limit feature | TBD | Day 2 |
90+
| | | | |
91+
92+
---
93+
## 6. Exit Criteria for Closing This File
94+
- All P0 + P1 tasks in sections 1–3 completed and referenced in Week 3 journal.
95+
- CI reflects new coverage gate and Postgres integration.
96+
- JavaDocs generated without warnings for P0 classes.
97+
- File archived (rename to `ASAP-closed-<date>.md`) or removed.
98+
99+
---
100+
*Created: 2025-09-27*
101+

‎docs/Weekly Plan Docs/Domain_&_Hosting_Checklist.md‎

Lines changed: 82 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,25 @@
1010
- Backend API: api.sameboat.<tld> → Render
1111
- DB: Neon (unchanged)
1212

13+
### CURRENT IMPLEMENTATION SNAPSHOT (Week 2 end)
14+
| Area | Status | Notes |
15+
|------|--------|-------|
16+
| Domain purchased | Pending | No domain configured in repo yet |
17+
| DNS zone created (Cloudflare) | Pending | All references still placeholder `<tld>` |
18+
| Backend prod profile | Ready | `application-prod.yml` with secure cookie & CORS |
19+
| CORS origins config | Ready | Uses `sameboat.cors.allowed-origins` list (dev + placeholders) |
20+
| Session cookie name | Implemented | Primary `SBSESSION`, alias `sb_session` accepted at runtime |
21+
| Cookie domain logic | Ready | Configurable via `sameboat.cookie.domain` (prod profile sets `.sameboat.<tld>`) |
22+
| Secure flag (prod) | Ready | `sameboat.cookie.secure=true` in prod profile |
23+
| TTL (prod) | Ready | 14 days (`sameboat.session.ttl-days=14`) |
24+
| Registration & login | Implemented | Sets `SBSESSION` HttpOnly cookie |
25+
| Logout clearing cookie | Implemented | Max-Age=0 consistent with domain/secure settings |
26+
| Observability logs | Implemented | INFO login/logout, WARN expired/invalid session |
27+
| Frontend deploy integration | Pending | No Netlify domain wiring yet |
28+
| API host deployment | Pending | Render setup not documented in repo scripts |
29+
| OpenAPI exposure | Pending | No `/v3/api-docs` yet |
30+
| HSTS | Deferred | Add after domain + HTTPS stable |
31+
1332
### Prereqs
1433
- Pick <tld> and buy sameboat.<tld> on Cloudflare Registrar.
1534
- Frontend repo ready (Vite). Backend repo builds a runnable JAR (./mvnw package) or Docker image.
@@ -60,51 +79,34 @@ Create public/_redirects (or in project root) with:
6079
_(Render provides `$PORT`;` -Dserver.port=$PORT` ensures Spring listens correctly.)_
6180

6281
#### Env vars (Render → Environment):
63-
- `SPRING_PROFILES_ACTIVE=prod`
64-
- `SPRING_DATASOURCE_URL=jdbc:postgresql://<neon-host>:5432/<db>?sslmode=require`
65-
- `SPRING_DATASOURCE_USERNAME=<user>`
66-
- `SPRING_DATASOURCE_PASSWORD=<pass>`
67-
- `SESSION_TTL_DAYS=14`
68-
- `COOKIE_DOMAIN=.sameboat.<tld>`
82+
```
83+
SPRING_PROFILES_ACTIVE=prod
84+
SPRING_DATASOURCE_URL=jdbc:postgresql://<neon-host>:5432/<db>?sslmode=require
85+
SPRING_DATASOURCE_USERNAME=<user>
86+
SPRING_DATASOURCE_PASSWORD=<pass>
87+
SAMEBOAT_COOKIE_DOMAIN=.sameboat.<tld>
88+
SAMEBOAT_COOKIE_SECURE=true
89+
SAMEBOAT_SESSION_TTL_DAYS=14
90+
SAMEBOAT_CORS_ALLOWED_ORIGINS=https://app.sameboat.<tld>,https://*.netlify.app
91+
```
92+
_(Spring relaxed binding maps environment uppercase underscore vars to sameboat.*)_
6993

7094
#### Custom domain (Render)
71-
- Add api.sameboat.<tld> → complete DNS (already CNAME’d) → enable HTTPS.
95+
- Add api.sameboat.<tld> → complete DNS CNAME → enable HTTPS.
7296

7397
### 4) Backend CORS & Cookie (prod)
7498

75-
Allow your real frontend + deploy previews; set cookie for parent domain:
76-
```text
77-
// CORS bean (prod)
78-
@Bean
79-
CorsConfigurationSource corsConfigurationSource() {
80-
var cfg = new CorsConfiguration();
81-
cfg.setAllowedOrigins(List.of(
82-
"https://app.sameboat.<tld>",
83-
"https://*.netlify.app" // Netlify Deploy Previews
84-
));
85-
cfg.setAllowedMethods(List.of("GET","POST","PUT","PATCH","DELETE","OPTIONS"));
86-
cfg.setAllowedHeaders(List.of("*"));
87-
cfg.setAllowCredentials(true);
88-
var src = new UrlBasedCorsConfigurationSource();
89-
src.registerCorsConfiguration("/**", cfg);
90-
return src;
91-
}
92-
```
93-
When issuing the session cookie on login:
99+
Current implementation (type-safe properties) already covers this; snippet illustrative only:
94100
```java
95-
ResponseCookie cookie = ResponseCookie.from("sb_session", sessionId)
96-
.httpOnly(true)
97-
.secure(true) // prod
98-
.sameSite("Lax")
99-
.domain(".sameboat.<tld>") // share across app/api subdomains
100-
.path("/")
101-
.maxAge(Duration.ofDays(14))
102-
.build();
103-
response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
101+
// In production, properties drive these values:
102+
props.getCors().getAllowedOrigins(); // includes app.sameboat.<tld>, *.netlify.app
103+
props.getCookie().isSecure(); // true
104+
props.getCookie().getDomain(); // .sameboat.<tld>
105+
props.getSession().getTtlDays(); // 14
104106
```
107+
Login cookie issuance uses `SBSESSION`; alias `sb_session` still accepted inbound.
105108

106109
---
107-
108110
### 5) Frontend dev settings (unchanged)
109111

110112
- [ ] `frontend-sameboat/.env.local`:
@@ -114,12 +116,11 @@ VITE_API_BASE=/api
114116
- [ ] `vite.config.ts` dev proxy:
115117
```ts
116118
server: {
117-
proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } }
119+
proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } }
118120
}
119121
```
120122

121123
---
122-
123124
### 6) Verification checklist
124125

125126
#### DNS/TLS
@@ -128,28 +129,60 @@ proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } }
128129
- [ ] Apex https://sameboat.<tld> redirects to https://app.sameboat.<tld>.
129130

130131
#### CORS & Cookies
131-
- [ ] From `app.sameboat.<tld>`, login sets sb_session; Secure; SameSite=Lax; Domain=.sameboat.<tld>.
132-
- [ ] XHR to `https://api.sameboat.<tld>/api/me` includes cookie and returns 200.
132+
- [ ] From `app.sameboat.<tld>`, login sets `SBSESSION` (Secure, HttpOnly, SameSite=Lax, Domain=.sameboat.<tld>).
133+
- [ ] XHR to `https://api.sameboat.<tld>/api/me` includes cookie → 200.
134+
- [ ] Expired session returns 401 JSON `{ "error": "SESSION_EXPIRED" }`.
135+
- [ ] Garbage cookie returns 401 JSON `{ "error": "UNAUTHENTICATED" }`.
133136

134137
#### Netlify Previews
135-
- [ ] A Deploy Preview domain (e.g., `https://deploy-preview-123--<site>.netlify.app`) can call the API (CORS allow list includes `*.netlify.app`).
138+
- [ ] A Deploy Preview (e.g., `https://deploy-preview-123--<site>.netlify.app`) can call API (CORS allow list includes `*.netlify.app`).
136139

137140
#### Backend logs
138-
- [ ] INFO on login/logout; WARN on invalid/expired session (as implemented).
141+
- [ ] INFO lines on login/logout; WARN on invalid/expired session visible in Render logs.
139142

140143
---
141-
142144
### 7) Nice-to-haves (later)
143-
- [ ] Enable HSTS in Cloudflare (after you confirm HTTPS everywhere).
145+
- [ ] Enable HSTS in Cloudflare (after HTTPS confirmed) & set min TLS 1.2.
144146
- [ ] Add OpenAPI (`springdoc-openapi`) to serve `/v3/api-docs`; generate TS types in FE.
145-
- [ ] Add ruleset requiring Backend CI checks to pass (already done).
146-
- [ ] Move repos to GitHub org; centralize secrets and rules.
147+
- [ ] WAF / rate limiting rule (basic bot mitigation) in Cloudflare.
148+
- [ ] Structured JSON logging (trace correlation) for auth events.
149+
- [ ] Observability: add `/actuator/metrics` + remote scraping.
147150

148151
---
149-
150152
### 8) Rollback plan (just in case)
151-
- [ ] Keep the old URLs live until new ones are verified.
152-
- [ ] If something breaks, point `app.` back to the Netlify default subdomain and `api`. back to Render’s `.onrender.com` origin (DNS CNAME changes are instant; allow up to a few minutes for global propagation).
153+
- [ ] Keep the old URLs (default Netlify & Render) live until new ones are verified.
154+
- [ ] If issues arise, revert DNS CNAMEs to provider defaults; TTL low (300s) to speed rollback.
155+
156+
---
157+
### 9) Post‑Week 2 Action Items
158+
| Priority | Action | Rationale |
159+
|----------|--------|-----------|
160+
| High | Acquire domain & provision Cloudflare zone | Unblocks all prod validation |
161+
| High | Deploy backend to Render with prod profile | Validate secure cookie + CORS in real env |
162+
| High | Deploy frontend to Netlify with API base pointing to Render | End‑to‑end session test |
163+
| Medium | Add migration test to main CI (Testcontainers) | Prevent drift & enforce schema early |
164+
| Medium | Add rate limiting / basic abuse guard | Mitigate brute force on login |
165+
| Medium | OpenAPI generation + publish docs | Improve FE contract stability |
166+
| Low | Session pruning job | Control table growth |
167+
| Low | Add HSTS + security headers | Harden prod edge |
168+
169+
### 10) Quick Validation Script (once deployed)
170+
```bash
171+
# Health
172+
curl -i https://api.sameboat.<tld>/actuator/health
173+
174+
# Register user
175+
curl -i -X POST https://api.sameboat.<tld>/auth/register \
176+
-H 'Content-Type: application/json' \
177+
-d '{"email":"smoke@sameboat.<tld>","password":"Abcdef1!"}'
178+
179+
# Extract cookie then call /me
180+
COOKIE=$(curl -i -s https://api.sameboat.<tld>/auth/login \
181+
-H 'Content-Type: application/json' \
182+
-d '{"email":"smoke@sameboat.<tld>","password":"Abcdef1!"}' | grep -Fi Set-Cookie | sed 's/;.*//')
183+
184+
curl -i https://api.sameboat.<tld>/me -H "Cookie: $COOKIE"
185+
```
153186

154187
---
155188
_For broader architecture overview see `docs/Architecture.md`._

0 commit comments

Comments
 (0)