# v2.0 Research: Architecture Notes

**Date:** 2026-05-15

## Integration Points

### Auth

Add a provider layer beside `backend/internal/auth`:

- `internal/auth/oauth.go` or `internal/identity/`
- `user_identities` table:
  - `id`
  - `user_id`
  - `provider` (`google`, `apple`)
  - `provider_subject`
  - `email`
  - `email_verified`
  - `created_at`
  - `updated_at`
  - unique `(provider, provider_subject)`

Keep `users` and `sessions` authoritative. Social sign-in should finish by using the same session store used by email/password login.

### Chat

Add:

- `tablo_messages` table:
  - `id`
  - `tablo_id`
  - `author_user_id`
  - `body`
  - `created_at`
  - `edited_at`
  - `deleted_at`
- `GET /tablos/{id}/messages` renders current message tab/history.
- `POST /tablos/{id}/messages` creates a message and returns a message fragment.
- `GET /tablos/{id}/messages/stream` holds an SSE connection and streams new message fragments or JSON payloads.

For a single-host v2, an in-process hub keyed by `tablo_id` is acceptable. The database remains the source of truth; the hub is only a delivery accelerator. If multi-instance deployment arrives later, replace hub fanout with Postgres LISTEN/NOTIFY or Redis.

### Etapes

Add:

- `etapes` table with `id`, `tablo_id`, `title`, `description`, `position`, timestamps.
- `tasks.etape_id nullable references etapes(id) on delete set null`.
- Keep existing `tasks.status` and `tasks.position`; etape grouping is orthogonal to kanban status.

This matches the constraint: only tasks may reference an etape, and etapes do not reference each other.

### Events / Planning

Add:

- `tablo_events` table with `id`, `tablo_id`, `created_by_user_id`, `title`, `description`, `location`, `starts_at`, `ends_at`, timestamps.
- `GET /planning` renders current user's event list/calendar-like agenda.
- `GET /tablos/{id}/events` renders a tablo events tab.
- Event ownership initially follows tablo ownership. If shared tablos arrive later, planning aggregation should include events from tablos the user can access.

## Phase Order

1. Social sign-in first, because it touches the existing auth/session foundation and should be isolated from collaboration schema changes.
2. Etapes next, because they extend existing tasks and can be tested without real-time concerns.
3. Events/planning next, because they add a new core domain with straightforward CRUD.
4. Chat last or near-last, because real-time delivery needs extra browser/manual verification and careful deployment behavior.

For roadmap ergonomics, chat can also be split into persistence first and real-time second.
