Add configuration files and update project documentation

- Introduced .editorconfig for consistent coding styles across the project.
- Added .golangci.yml for Go linting configuration.
- Updated AGENTS.md to clarify project structure and components.
- Enhanced CONTRIBUTING.md with Makefile usage for common tasks.
- Updated Dockerfiles to use Go 1.24 and improved build instructions.
- Refined README.md and deployment documentation for clarity.
- Added testing documentation in testing.md for backend and frontend tests.
- Introduced Makefile for streamlined development commands and tasks.

internal/app/store/db.go

@@ -1,6 +1,7 @@
 package store
 
 import (
+	"context"
 	"strconv"
 
 	"go.etcd.io/bbolt"
@@ -16,19 +17,29 @@ func New(db *bbolt.DB) *Store {
 	return &Store{db: db}
 }
 
-// View runs fn in a read-only transaction.
-func (s *Store) View(fn func(tx *bbolt.Tx) error) error {
-	return s.db.View(fn)
+// View runs fn in a read-only transaction. Checks context before starting.
+func (s *Store) View(ctx context.Context, fn func(tx *bbolt.Tx) error) error {
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
+		return s.db.View(fn)
+	}
 }
 
-// Update runs fn in a read-write transaction.
-func (s *Store) Update(fn func(tx *bbolt.Tx) error) error {
-	return s.db.Update(fn)
+// Update runs fn in a read-write transaction. Checks context before starting.
+func (s *Store) Update(ctx context.Context, fn func(tx *bbolt.Tx) error) error {
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
+		return s.db.Update(fn)
+	}
 }
 
 // --- Users ---
 
-// GetUser returns raw user bytes by username, or nil if not found.
+// GetUser returns the raw JSON for a user, or nil if not found.
 func (s *Store) GetUser(tx *bbolt.Tx, username string) []byte {
 	b := tx.Bucket(BucketUsers)
 	if b == nil {
@@ -37,7 +48,7 @@ func (s *Store) GetUser(tx *bbolt.Tx, username string) []byte {
 	return b.Get([]byte(username))
 }
 
-// PutUser stores user bytes by username.
+// PutUser stores a user (creates the bucket if needed).
 func (s *Store) PutUser(tx *bbolt.Tx, username string, raw []byte) error {
 	b, err := tx.CreateBucketIfNotExists(BucketUsers)
 	if err != nil {
@@ -46,7 +57,7 @@ func (s *Store) PutUser(tx *bbolt.Tx, username string, raw []byte) error {
 	return b.Put([]byte(username), raw)
 }
 
-// DeleteUser removes a user.
+// DeleteUser removes a user by username.
 func (s *Store) DeleteUser(tx *bbolt.Tx, username string) error {
 	b := tx.Bucket(BucketUsers)
 	if b == nil {
@@ -55,7 +66,7 @@ func (s *Store) DeleteUser(tx *bbolt.Tx, username string) error {
 	return b.Delete([]byte(username))
 }
 
-// ForEachUser calls fn for each user key.
+// ForEachUser iterates over all users.
 func (s *Store) ForEachUser(tx *bbolt.Tx, fn func(k, v []byte) error) error {
 	b := tx.Bucket(BucketUsers)
 	if b == nil {
@@ -64,7 +75,7 @@ func (s *Store) ForEachUser(tx *bbolt.Tx, fn func(k, v []byte) error) error {
 	return b.ForEach(fn)
 }
 
-// UserCount returns the number of users.
+// UserCount returns the number of users in the database.
 func (s *Store) UserCount(tx *bbolt.Tx) int {
 	b := tx.Bucket(BucketUsers)
 	if b == nil {
@@ -75,7 +86,7 @@ func (s *Store) UserCount(tx *bbolt.Tx) int {
 
 // --- Sessions ---
 
-// GetSession returns raw session bytes by ID, or nil if not found.
+// GetSession returns the raw JSON for a session, or nil if not found.
 func (s *Store) GetSession(tx *bbolt.Tx, id string) []byte {
 	b := tx.Bucket(BucketSessions)
 	if b == nil {
@@ -84,7 +95,7 @@ func (s *Store) GetSession(tx *bbolt.Tx, id string) []byte {
 	return b.Get([]byte(id))
 }
 
-// PutSession stores session bytes.
+// PutSession stores a session.
 func (s *Store) PutSession(tx *bbolt.Tx, id string, raw []byte) error {
 	b, err := tx.CreateBucketIfNotExists(BucketSessions)
 	if err != nil {
@@ -93,7 +104,7 @@ func (s *Store) PutSession(tx *bbolt.Tx, id string, raw []byte) error {
 	return b.Put([]byte(id), raw)
 }
 
-// DeleteSession removes a session.
+// DeleteSession removes a session by ID.
 func (s *Store) DeleteSession(tx *bbolt.Tx, id string) error {
 	b := tx.Bucket(BucketSessions)
 	if b == nil {
@@ -104,7 +115,7 @@ func (s *Store) DeleteSession(tx *bbolt.Tx, id string) error {
 
 // --- Tokens ---
 
-// GetTokenUser returns username for token, or nil if not found.
+// GetTokenUser returns the username associated with a token, or nil.
 func (s *Store) GetTokenUser(tx *bbolt.Tx, token string) []byte {
 	b := tx.Bucket(BucketTokens)
 	if b == nil {
@@ -113,7 +124,7 @@ func (s *Store) GetTokenUser(tx *bbolt.Tx, token string) []byte {
 	return b.Get([]byte(token))
 }
 
-// PutToken stores token -> username mapping.
+// PutToken associates a token with a username.
 func (s *Store) PutToken(tx *bbolt.Tx, token, username string) error {
 	b, err := tx.CreateBucketIfNotExists(BucketTokens)
 	if err != nil {
@@ -133,7 +144,7 @@ func (s *Store) DeleteToken(tx *bbolt.Tx, token string) error {
 
 // --- Config ---
 
-// GetConfig returns config value by key.
+// GetConfig returns a config value by key, or nil.
 func (s *Store) GetConfig(tx *bbolt.Tx, key string) []byte {
 	b := tx.Bucket(BucketConfig)
 	if b == nil {
@@ -142,7 +153,7 @@ func (s *Store) GetConfig(tx *bbolt.Tx, key string) []byte {
 	return b.Get([]byte(key))
 }
 
-// PutConfig stores config value.
+// PutConfig stores a config key-value pair.
 func (s *Store) PutConfig(tx *bbolt.Tx, key string, value []byte) error {
 	b, err := tx.CreateBucketIfNotExists(BucketConfig)
 	if err != nil {
@@ -162,7 +173,7 @@ func (s *Store) DeleteConfig(tx *bbolt.Tx, key string) error {
 
 // --- Maps ---
 
-// GetMap returns raw MapInfo bytes by ID.
+// GetMap returns the raw JSON for a map, or nil if not found.
 func (s *Store) GetMap(tx *bbolt.Tx, id int) []byte {
 	b := tx.Bucket(BucketMaps)
 	if b == nil {
@@ -171,7 +182,7 @@ func (s *Store) GetMap(tx *bbolt.Tx, id int) []byte {
 	return b.Get([]byte(strconv.Itoa(id)))
 }
 
-// PutMap stores MapInfo.
+// PutMap stores a map entry.
 func (s *Store) PutMap(tx *bbolt.Tx, id int, raw []byte) error {
 	b, err := tx.CreateBucketIfNotExists(BucketMaps)
 	if err != nil {
@@ -180,7 +191,7 @@ func (s *Store) PutMap(tx *bbolt.Tx, id int, raw []byte) error {
 	return b.Put([]byte(strconv.Itoa(id)), raw)
 }
 
-// DeleteMap removes a map.
+// DeleteMap removes a map by ID.
 func (s *Store) DeleteMap(tx *bbolt.Tx, id int) error {
 	b := tx.Bucket(BucketMaps)
 	if b == nil {
@@ -189,7 +200,7 @@ func (s *Store) DeleteMap(tx *bbolt.Tx, id int) error {
 	return b.Delete([]byte(strconv.Itoa(id)))
 }
 
-// MapsNextSequence returns next map ID sequence.
+// MapsNextSequence returns the next auto-increment ID for maps.
 func (s *Store) MapsNextSequence(tx *bbolt.Tx) (uint64, error) {
 	b, err := tx.CreateBucketIfNotExists(BucketMaps)
 	if err != nil {
@@ -198,7 +209,7 @@ func (s *Store) MapsNextSequence(tx *bbolt.Tx) (uint64, error) {
 	return b.NextSequence()
 }
 
-// MapsSetSequence sets map bucket sequence.
+// MapsSetSequence sets the maps bucket sequence counter.
 func (s *Store) MapsSetSequence(tx *bbolt.Tx, v uint64) error {
 	b := tx.Bucket(BucketMaps)
 	if b == nil {
@@ -207,7 +218,7 @@ func (s *Store) MapsSetSequence(tx *bbolt.Tx, v uint64) error {
 	return b.SetSequence(v)
 }
 
-// ForEachMap calls fn for each map.
+// ForEachMap iterates over all maps.
 func (s *Store) ForEachMap(tx *bbolt.Tx, fn func(k, v []byte) error) error {
 	b := tx.Bucket(BucketMaps)
 	if b == nil {
@@ -218,7 +229,7 @@ func (s *Store) ForEachMap(tx *bbolt.Tx, fn func(k, v []byte) error) error {
 
 // --- Grids ---
 
-// GetGrid returns raw GridData bytes by ID.
+// GetGrid returns the raw JSON for a grid, or nil if not found.
 func (s *Store) GetGrid(tx *bbolt.Tx, id string) []byte {
 	b := tx.Bucket(BucketGrids)
 	if b == nil {
@@ -227,7 +238,7 @@ func (s *Store) GetGrid(tx *bbolt.Tx, id string) []byte {
 	return b.Get([]byte(id))
 }
 
-// PutGrid stores GridData.
+// PutGrid stores a grid entry.
 func (s *Store) PutGrid(tx *bbolt.Tx, id string, raw []byte) error {
 	b, err := tx.CreateBucketIfNotExists(BucketGrids)
 	if err != nil {
@@ -236,7 +247,7 @@ func (s *Store) PutGrid(tx *bbolt.Tx, id string, raw []byte) error {
 	return b.Put([]byte(id), raw)
 }
 
-// DeleteGrid removes a grid.
+// DeleteGrid removes a grid by ID.
 func (s *Store) DeleteGrid(tx *bbolt.Tx, id string) error {
 	b := tx.Bucket(BucketGrids)
 	if b == nil {
@@ -245,7 +256,7 @@ func (s *Store) DeleteGrid(tx *bbolt.Tx, id string) error {
 	return b.Delete([]byte(id))
 }
 
-// ForEachGrid calls fn for each grid.
+// ForEachGrid iterates over all grids.
 func (s *Store) ForEachGrid(tx *bbolt.Tx, fn func(k, v []byte) error) error {
 	b := tx.Bucket(BucketGrids)
 	if b == nil {
@@ -256,7 +267,7 @@ func (s *Store) ForEachGrid(tx *bbolt.Tx, fn func(k, v []byte) error) error {
 
 // --- Tiles (nested: mapid -> zoom -> coord) ---
 
-// GetTile returns raw TileData bytes.
+// GetTile returns the raw JSON for a tile at the given map/zoom/coord, or nil.
 func (s *Store) GetTile(tx *bbolt.Tx, mapID, zoom int, coordKey string) []byte {
 	tiles := tx.Bucket(BucketTiles)
 	if tiles == nil {
@@ -273,7 +284,7 @@ func (s *Store) GetTile(tx *bbolt.Tx, mapID, zoom int, coordKey string) []byte {
 	return zoomB.Get([]byte(coordKey))
 }
 
-// PutTile stores TileData.
+// PutTile stores a tile entry (creates nested buckets as needed).
 func (s *Store) PutTile(tx *bbolt.Tx, mapID, zoom int, coordKey string, raw []byte) error {
 	tiles, err := tx.CreateBucketIfNotExists(BucketTiles)
 	if err != nil {
@@ -290,7 +301,7 @@ func (s *Store) PutTile(tx *bbolt.Tx, mapID, zoom int, coordKey string, raw []by
 	return zoomB.Put([]byte(coordKey), raw)
 }
 
-// DeleteTilesBucket removes the tiles bucket (for wipe).
+// DeleteTilesBucket removes the entire tiles bucket.
 func (s *Store) DeleteTilesBucket(tx *bbolt.Tx) error {
 	if tx.Bucket(BucketTiles) == nil {
 		return nil
@@ -298,7 +309,7 @@ func (s *Store) DeleteTilesBucket(tx *bbolt.Tx) error {
 	return tx.DeleteBucket(BucketTiles)
 }
 
-// ForEachTile calls fn for each tile in the nested structure.
+// ForEachTile iterates over all tiles across all maps and zoom levels.
 func (s *Store) ForEachTile(tx *bbolt.Tx, fn func(mapK, zoomK, coordK, v []byte) error) error {
 	tiles := tx.Bucket(BucketTiles)
 	if tiles == nil {
@@ -321,7 +332,7 @@ func (s *Store) ForEachTile(tx *bbolt.Tx, fn func(mapK, zoomK, coordK, v []byte)
 	})
 }
 
-// GetTilesMapBucket returns the bucket for a map's tiles, or nil.
+// GetTilesMapBucket returns the tiles sub-bucket for a specific map, or nil.
 func (s *Store) GetTilesMapBucket(tx *bbolt.Tx, mapID int) *bbolt.Bucket {
 	tiles := tx.Bucket(BucketTiles)
 	if tiles == nil {
@@ -330,7 +341,7 @@ func (s *Store) GetTilesMapBucket(tx *bbolt.Tx, mapID int) *bbolt.Bucket {
 	return tiles.Bucket([]byte(strconv.Itoa(mapID)))
 }
 
-// CreateTilesMapBucket creates and returns the bucket for a map's tiles.
+// CreateTilesMapBucket returns or creates the tiles sub-bucket for a specific map.
 func (s *Store) CreateTilesMapBucket(tx *bbolt.Tx, mapID int) (*bbolt.Bucket, error) {
 	tiles, err := tx.CreateBucketIfNotExists(BucketTiles)
 	if err != nil {
@@ -339,18 +350,22 @@ func (s *Store) CreateTilesMapBucket(tx *bbolt.Tx, mapID int) (*bbolt.Bucket, er
 	return tiles.CreateBucketIfNotExists([]byte(strconv.Itoa(mapID)))
 }
 
-// DeleteTilesMapBucket removes a map's tile bucket.
+// DeleteTilesMapBucket removes the tiles sub-bucket for a specific map.
 func (s *Store) DeleteTilesMapBucket(tx *bbolt.Tx, mapID int) error {
 	tiles := tx.Bucket(BucketTiles)
 	if tiles == nil {
 		return nil
 	}
-	return tiles.DeleteBucket([]byte(strconv.Itoa(mapID)))
+	key := []byte(strconv.Itoa(mapID))
+	if tiles.Bucket(key) == nil {
+		return nil
+	}
+	return tiles.DeleteBucket(key)
 }
 
 // --- Markers (nested: grid bucket, id bucket) ---
 
-// GetMarkersGridBucket returns the markers-by-grid bucket.
+// GetMarkersGridBucket returns the markers grid sub-bucket, or nil.
 func (s *Store) GetMarkersGridBucket(tx *bbolt.Tx) *bbolt.Bucket {
 	mb := tx.Bucket(BucketMarkers)
 	if mb == nil {
@@ -359,7 +374,7 @@ func (s *Store) GetMarkersGridBucket(tx *bbolt.Tx) *bbolt.Bucket {
 	return mb.Bucket(BucketMarkersGrid)
 }
 
-// GetMarkersIDBucket returns the markers-by-id bucket.
+// GetMarkersIDBucket returns the markers ID sub-bucket, or nil.
 func (s *Store) GetMarkersIDBucket(tx *bbolt.Tx) *bbolt.Bucket {
 	mb := tx.Bucket(BucketMarkers)
 	if mb == nil {
@@ -368,7 +383,7 @@ func (s *Store) GetMarkersIDBucket(tx *bbolt.Tx) *bbolt.Bucket {
 	return mb.Bucket(BucketMarkersID)
 }
 
-// CreateMarkersBuckets creates markers, grid, and id buckets.
+// CreateMarkersBuckets returns or creates both markers sub-buckets (grid and id).
 func (s *Store) CreateMarkersBuckets(tx *bbolt.Tx) (*bbolt.Bucket, *bbolt.Bucket, error) {
 	mb, err := tx.CreateBucketIfNotExists(BucketMarkers)
 	if err != nil {
@@ -385,7 +400,7 @@ func (s *Store) CreateMarkersBuckets(tx *bbolt.Tx) (*bbolt.Bucket, *bbolt.Bucket
 	return grid, idB, nil
 }
 
-// MarkersNextSequence returns next marker ID.
+// MarkersNextSequence returns the next auto-increment ID for markers.
 func (s *Store) MarkersNextSequence(tx *bbolt.Tx) (uint64, error) {
 	mb := tx.Bucket(BucketMarkers)
 	if mb == nil {
@@ -400,7 +415,7 @@ func (s *Store) MarkersNextSequence(tx *bbolt.Tx) (uint64, error) {
 
 // --- OAuth states ---
 
-// GetOAuthState returns raw state bytes.
+// GetOAuthState returns the raw JSON for an OAuth state, or nil.
 func (s *Store) GetOAuthState(tx *bbolt.Tx, state string) []byte {
 	b := tx.Bucket(BucketOAuthStates)
 	if b == nil {
@@ -409,7 +424,7 @@ func (s *Store) GetOAuthState(tx *bbolt.Tx, state string) []byte {
 	return b.Get([]byte(state))
 }
 
-// PutOAuthState stores state.
+// PutOAuthState stores an OAuth state entry.
 func (s *Store) PutOAuthState(tx *bbolt.Tx, state string, raw []byte) error {
 	b, err := tx.CreateBucketIfNotExists(BucketOAuthStates)
 	if err != nil {
@@ -418,7 +433,7 @@ func (s *Store) PutOAuthState(tx *bbolt.Tx, state string, raw []byte) error {
 	return b.Put([]byte(state), raw)
 }
 
-// DeleteOAuthState removes state.
+// DeleteOAuthState removes an OAuth state entry.
 func (s *Store) DeleteOAuthState(tx *bbolt.Tx, state string) error {
 	b := tx.Bucket(BucketOAuthStates)
 	if b == nil {
@@ -429,16 +444,15 @@ func (s *Store) DeleteOAuthState(tx *bbolt.Tx, state string) error {
 
 // --- Bucket existence (for wipe) ---
 
-// BucketExists returns true if the bucket exists.
+// BucketExists returns true if a top-level bucket with the given name exists.
 func (s *Store) BucketExists(tx *bbolt.Tx, name []byte) bool {
 	return tx.Bucket(name) != nil
 }
 
-// DeleteBucket removes a bucket.
+// DeleteBucket removes a top-level bucket (no-op if it doesn't exist).
 func (s *Store) DeleteBucket(tx *bbolt.Tx, name []byte) error {
 	if tx.Bucket(name) == nil {
 		return nil
 	}
 	return tx.DeleteBucket(name)
 }
-