xtablo-source/.planning/research/ARCHITECTURE.md

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.