Propose architecture design for NetColab application

[FisherSkyi]

Purpose

Propose and discuss the architecture design for the NetColab application. Establish the core components, technology stack, and high-level system design to guide further implementation.

Requirements

• Define the main components/services/modules of the application
• Suggest technology stack choices (backend, frontend, database, etc.)
• Provide diagrams or sketches if possible (can be attached in comments)
• Consider scalability, maintainability, and extensibility

Outcome

A proposed architecture design that all team members can review, discuss, and approve to serve as a blueprint for development.

[FisherSkyi]

@claude attempt this

[claude]

Claude finished @FisherSkyi's task in 2m 39s —— View job • claude/issue-2-20260321-1420 • Create PR ➔

---

Architecture Design for NetColab

• Gather context from repository
• Analyze existing codebase (React 18 + TS + Vite frontend, all data mocked, no backend yet)
• Propose architecture design
• Create architecture documentation file (docs/ARCHITECTURE.md)
• Commit and push changes

---

Here's the proposed architecture for NetColab, documented in docs/ARCHITECTURE.md.

System Design Summary

Core stack:

• Frontend (existing): React 18 + TypeScript + Vite, React Query for server state, Socket.io-client for real-time
• Backend (new): Node.js + Hono (TypeScript-native, fast, edge-ready) with Socket.io
• Database: PostgreSQL — relational integrity for users/rooms/messages/versions, with Drizzle ORM
• Cache / Real-time: Redis — pub/sub for cross-instance Socket.io, presence TTL, session store
• AI Proxy: Server-side routing by model to Anthropic / OpenAI / Google AI SDKs

Key architectural decisions

Concern	Decision	Rationale
Backend framework	Hono	TypeScript-first, minimal, works on Node/Bun/edge
Real-time	Socket.io rooms	Handles presence, reconnection, fan-out built-in
Database	PostgreSQL + Drizzle	Strong schema for relational chat/audit data
AI routing	Server-side proxy with SSE streaming	Keeps API keys secure; enables multi-model
Scaling	Redis Socket.io adapter	Stateless API servers, pub/sub decouples fan-out
Auth	JWT (15min) + refresh tokens in Redis	Stateless access + revocable refresh

Data model (PostgreSQL)

• users — id, email, name, avatar, color
• rooms — id, title, emoji, created_by, last_activity
• room_participants — room_id × user_id join table
• messages — id, room_id, user_id, content, type (user/ai/queued), model
• versions — audit log of actions per room

Real-time (Socket.io events)

server → room:  message:new · message:updated · presence:join · presence:leave · ai:typing · ai:done
client → server: message:send · message:queue · room:flush

Implementation milestones

1. Phase 1 — Backend scaffold (Hono + Docker Compose + DB migrations + Auth)
2. Phase 2 — Room & Message REST APIs
3. Phase 3 — Socket.io real-time + Redis presence
4. Phase 4 — Multi-model AI proxy with SSE streaming
5. Phase 5 — Frontend migration (replace mock data with API + live sockets)
6. Phase 6 — Rate limiting, E2E tests, CI/CD, production deployment

·