gns3-server/docs/gns3-copilot/user-preferences-api-roadmap.md

This document is a roadmap/planning document. The described features have not been implemented yet.

User Preferences API — Roadmap

Problem

Currently, user-specific preferences (UI theme, language, AI Copilot settings, workspace layout, etc.) can only be stored in browser localStorage. This has several drawbacks:

1. localStorage clearing — clearing browser data or switching devices loses all settings
2. No cross-device sync — users must reconfigure preferences on each device
3. No API access — CLI tools and third-party clients cannot read/write preferences
4. Fragile persistence — localStorage can be cleared by browser maintenance or incognito mode

Proposed API

Method	Path	Description
GET	/v3/access/users/me/preferences	Get all preferences for current user
PUT	/v3/access/users/me/preferences	Merge preferences (top-level merge, not replace)
DELETE	/v3/access/users/me/preferences	Clear all preferences

Storage

A preferences JSON column on the existing users table:

• Type: JSON, non-nullable, default '{}'
• No schema enforcement — clients can store arbitrary key-value pairs
• Examples: {"theme": "dark", "language": "zh-CN", "copilot_default_mode": "teaching_assistant"}

Implementation Plan

1. Add preferences JSON column to User ORM model
2. Create Alembic migration
3. Add UserPreferencesUpdate Pydantic schema with extra="allow"
4. Add get_user_preferences() and update_user_preferences() to UsersRepository
5. Add three endpoints to users.py router: GET/PUT/DELETE /me/preferences

Related Files

File	Role
gns3server/db/models/user.py	User ORM model
gns3server/db/repositories/users.py	UsersRepository with database operations
gns3server/api/routes/controller/users.py	User API router
gns3server/schemas/	Pydantic schemas
gns3server/db/versions/	Alembic migrations

Status

• Add preferences JSON column to User ORM model
• Create Alembic migration
• Add UserPreferencesUpdate schema
• Add repository methods
• Add API endpoints to users.py router