feat(backend): add WeatherService

Manage per-user WeatherSource instances via FeedSourceProvider,
following the same pattern as LocationService. Wire into
FeedEngineService so weather data is included in the feed.

Co-authored-by: Ona <no-reply@ona.com>

.devcontainer/devcontainer.json

@@ -10,6 +10,7 @@
 		"context": ".",
 		"dockerfile": "Dockerfile"
 	},
+	"postCreateCommand": "bun install",
 	"postStartCommand": "./scripts/setup-git.sh && ./scripts/setup-nvim.sh"
 	// Features add additional features to your environment. See https://containers.dev/features
 	// Beware: features are not supported on all platforms and may have unintended side-effects.

apps/aris-backend/.env.example

@@ -6,3 +6,9 @@ BETTER_AUTH_SECRET=
 
 # Base URL of the backend
 BETTER_AUTH_URL=http://localhost:3000
+
+# Apple WeatherKit credentials
+WEATHERKIT_PRIVATE_KEY=
+WEATHERKIT_KEY_ID=
+WEATHERKIT_TEAM_ID=
+WEATHERKIT_SERVICE_ID=

apps/aris-backend/package.json

@@ -12,6 +12,9 @@
 		"@aris/core": "workspace:*",
 		"@aris/source-location": "workspace:*",
 		"@aris/source-weatherkit": "workspace:*",
+		"@hono/trpc-server": "^0.3",
+		"@trpc/server": "^11",
+		"arktype": "^2.1.29",
 		"better-auth": "^1",
 		"hono": "^4",
 		"pg": "^8"

apps/aris-backend/src/feed/service.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, mock, test } from "bun:test"
+
+import { LocationService } from "../location/service.ts"
+import { FeedEngineService } from "./service.ts"
+
+describe("FeedEngineService", () => {
+	test("engineForUser creates engine on first call", () => {
+		const locationService = new LocationService()
+		const service = new FeedEngineService([locationService])
+
+		const engine = service.engineForUser("user-1")
+
+		expect(engine).toBeDefined()
+	})
+
+	test("engineForUser returns same engine for same user", () => {
+		const locationService = new LocationService()
+		const service = new FeedEngineService([locationService])
+
+		const engine1 = service.engineForUser("user-1")
+		const engine2 = service.engineForUser("user-1")
+
+		expect(engine1).toBe(engine2)
+	})
+
+	test("engineForUser returns different engines for different users", () => {
+		const locationService = new LocationService()
+		const service = new FeedEngineService([locationService])
+
+		const engine1 = service.engineForUser("user-1")
+		const engine2 = service.engineForUser("user-2")
+
+		expect(engine1).not.toBe(engine2)
+	})
+
+	test("engineForUser registers sources from all providers", async () => {
+		const locationService = new LocationService()
+		const service = new FeedEngineService([locationService])
+
+		const engine = service.engineForUser("user-1")
+		const result = await engine.refresh()
+
+		expect(result.errors).toHaveLength(0)
+	})
+
+	test("engineForUser works with empty providers array", async () => {
+		const service = new FeedEngineService([])
+
+		const engine = service.engineForUser("user-1")
+		const result = await engine.refresh()
+
+		expect(result.errors).toHaveLength(0)
+		expect(result.items).toHaveLength(0)
+	})
+
+	test("refresh returns feed result", async () => {
+		const locationService = new LocationService()
+		const service = new FeedEngineService([locationService])
+
+		const result = await service.refresh("user-1")
+
+		expect(result).toHaveProperty("context")
+		expect(result).toHaveProperty("items")
+		expect(result).toHaveProperty("errors")
+		expect(result.context.time).toBeInstanceOf(Date)
+	})
+
+	test("refresh uses location from LocationService", async () => {
+		const locationService = new LocationService()
+		const service = new FeedEngineService([locationService])
+		const location = {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		}
+
+		// Create engine first, then update location
+		service.engineForUser("user-1")
+		locationService.updateUserLocation("user-1", location)
+
+		const result = await service.refresh("user-1")
+
+		expect(result.context.location).toEqual(location)
+	})
+
+	test("subscribe receives updates", async () => {
+		const locationService = new LocationService()
+		const service = new FeedEngineService([locationService])
+		const callback = mock()
+
+		service.subscribe("user-1", callback)
+
+		// Push location to trigger update
+		locationService.updateUserLocation("user-1", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		// Wait for async update propagation
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).toHaveBeenCalled()
+	})
+
+	test("subscribe returns unsubscribe function", async () => {
+		const locationService = new LocationService()
+		const service = new FeedEngineService([locationService])
+		const callback = mock()
+
+		const unsubscribe = service.subscribe("user-1", callback)
+
+		unsubscribe()
+
+		locationService.updateUserLocation("user-1", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).not.toHaveBeenCalled()
+	})
+
+	test("removeUser stops engine and removes it", async () => {
+		const locationService = new LocationService()
+		const service = new FeedEngineService([locationService])
+		const callback = mock()
+
+		service.subscribe("user-1", callback)
+
+		service.removeUser("user-1")
+
+		// Push location - should not trigger update since engine is stopped
+		locationService.feedSourceForUser("user-1")
+		locationService.updateUserLocation("user-1", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).not.toHaveBeenCalled()
+	})
+
+	test("removeUser allows new engine to be created", () => {
+		const locationService = new LocationService()
+		const service = new FeedEngineService([locationService])
+
+		const engine1 = service.engineForUser("user-1")
+		service.removeUser("user-1")
+		const engine2 = service.engineForUser("user-1")
+
+		expect(engine1).not.toBe(engine2)
+	})
+})

apps/aris-backend/src/feed/service.ts

@@ -0,0 +1,75 @@
+import { FeedEngine, type FeedResult, type FeedSource, type FeedSubscriber } from "@aris/core"
+
+/**
+ * Provides a FeedSource instance for a user.
+ */
+export interface FeedSourceProvider {
+	feedSourceForUser(userId: string): FeedSource
+}
+
+/**
+ * Manages FeedEngine instances per user.
+ *
+ * Receives FeedSource instances from injected providers and wires them
+ * into per-user engines. Engines are auto-started on creation.
+ */
+export class FeedEngineService {
+	private engines = new Map<string, FeedEngine>()
+
+	constructor(private readonly providers: FeedSourceProvider[]) {}
+
+	/**
+	 * Get or create a FeedEngine for a user.
+	 * Automatically registers sources and starts the engine.
+	 */
+	engineForUser(userId: string): FeedEngine {
+		let engine = this.engines.get(userId)
+		if (!engine) {
+			engine = this.createEngine(userId)
+			this.engines.set(userId, engine)
+		}
+		return engine
+	}
+
+	/**
+	 * Refresh a user's feed.
+	 */
+	async refresh(userId: string): Promise<FeedResult> {
+		const engine = this.engineForUser(userId)
+		return engine.refresh()
+	}
+
+	/**
+	 * Subscribe to feed updates for a user.
+	 * Returns unsubscribe function.
+	 */
+	subscribe(userId: string, callback: FeedSubscriber): () => void {
+		const engine = this.engineForUser(userId)
+		return engine.subscribe(callback)
+	}
+
+	/**
+	 * Remove a user's FeedEngine.
+	 * Stops the engine and cleans up resources.
+	 */
+	removeUser(userId: string): void {
+		const engine = this.engines.get(userId)
+		if (engine) {
+			engine.stop()
+			this.engines.delete(userId)
+		}
+	}
+
+	private createEngine(userId: string): FeedEngine {
+		const engine = new FeedEngine()
+
+		for (const provider of this.providers) {
+			const source = provider.feedSourceForUser(userId)
+			engine.register(source)
+		}
+
+		engine.start()
+
+		return engine
+	}
+}

apps/aris-backend/src/lib/error.ts

@@ -0,0 +1,8 @@
+export class UserNotFoundError extends Error {
+	constructor(
+		public readonly userId: string,
+		message?: string,
+	) {
+		super(message ? `${message}: user not found: ${userId}` : `User not found: ${userId}`)
+	}
+}

apps/aris-backend/src/location/router.ts

@@ -0,0 +1,37 @@
+import { TRPCError } from "@trpc/server"
+import { type } from "arktype"
+
+import type { TRPC } from "../trpc/router.ts"
+import type { LocationService } from "./service.ts"
+
+import { UserNotFoundError } from "../lib/error.ts"
+
+const locationInput = type({
+	lat: "number",
+	lng: "number",
+	accuracy: "number",
+	timestamp: "Date",
+})
+
+export function createLocationRouter(
+	t: TRPC,
+	{ locationService }: { locationService: LocationService },
+) {
+	return t.router({
+		update: t.procedure.input(locationInput).mutation(({ input, ctx }) => {
+			try {
+				locationService.updateUserLocation(ctx.user.id, {
+					lat: input.lat,
+					lng: input.lng,
+					accuracy: input.accuracy,
+					timestamp: input.timestamp,
+				})
+			} catch (error) {
+				if (error instanceof UserNotFoundError) {
+					throw new TRPCError({ code: "NOT_FOUND", message: error.message })
+				}
+				throw error
+			}
+		}),
+	})
+}

apps/aris-backend/src/location/service.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test"
+
+import { UserNotFoundError } from "../lib/error.ts"
+import { LocationService } from "./service.ts"
+
+describe("LocationService", () => {
+	test("feedSourceForUser creates source on first call", () => {
+		const service = new LocationService()
+		const source = service.feedSourceForUser("user-1")
+
+		expect(source).toBeDefined()
+		expect(source.id).toBe("location")
+	})
+
+	test("feedSourceForUser returns same source for same user", () => {
+		const service = new LocationService()
+		const source1 = service.feedSourceForUser("user-1")
+		const source2 = service.feedSourceForUser("user-1")
+
+		expect(source1).toBe(source2)
+	})
+
+	test("feedSourceForUser returns different sources for different users", () => {
+		const service = new LocationService()
+		const source1 = service.feedSourceForUser("user-1")
+		const source2 = service.feedSourceForUser("user-2")
+
+		expect(source1).not.toBe(source2)
+	})
+
+	test("updateUserLocation updates the source", () => {
+		const service = new LocationService()
+		const source = service.feedSourceForUser("user-1")
+		const location = {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		}
+
+		service.updateUserLocation("user-1", location)
+
+		expect(source.lastLocation).toEqual(location)
+	})
+
+	test("updateUserLocation throws if source does not exist", () => {
+		const service = new LocationService()
+		const location = {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		}
+
+		expect(() => service.updateUserLocation("user-1", location)).toThrow(UserNotFoundError)
+	})
+
+	test("lastUserLocation returns null for unknown user", () => {
+		const service = new LocationService()
+
+		expect(service.lastUserLocation("unknown")).toBeNull()
+	})
+
+	test("lastUserLocation returns last location", () => {
+		const service = new LocationService()
+		service.feedSourceForUser("user-1")
+		const location1 = {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		}
+		const location2 = {
+			lat: 52.0,
+			lng: -0.2,
+			accuracy: 5,
+			timestamp: new Date(),
+		}
+
+		service.updateUserLocation("user-1", location1)
+		service.updateUserLocation("user-1", location2)
+
+		expect(service.lastUserLocation("user-1")).toEqual(location2)
+	})
+
+	test("removeUser removes the source", () => {
+		const service = new LocationService()
+		service.feedSourceForUser("user-1")
+		const location = {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		}
+
+		service.updateUserLocation("user-1", location)
+		service.removeUser("user-1")
+
+		expect(service.lastUserLocation("user-1")).toBeNull()
+	})
+
+	test("removeUser allows new source to be created", () => {
+		const service = new LocationService()
+		const source1 = service.feedSourceForUser("user-1")
+
+		service.removeUser("user-1")
+		const source2 = service.feedSourceForUser("user-1")
+
+		expect(source1).not.toBe(source2)
+	})
+})

apps/aris-backend/src/location/service.ts

@@ -0,0 +1,57 @@
+import { LocationSource, type Location } from "@aris/source-location"
+
+import type { FeedSourceProvider } from "../feed/service.ts"
+
+import { UserNotFoundError } from "../lib/error.ts"
+
+/**
+ * Manages LocationSource instances per user.
+ */
+export class LocationService implements FeedSourceProvider {
+	private sources = new Map<string, LocationSource>()
+
+	/**
+	 * Get or create a LocationSource for a user.
+	 * @param userId - The user's unique identifier
+	 * @returns The user's LocationSource instance
+	 */
+	feedSourceForUser(userId: string): LocationSource {
+		let source = this.sources.get(userId)
+		if (!source) {
+			source = new LocationSource()
+			this.sources.set(userId, source)
+		}
+		return source
+	}
+
+	/**
+	 * Update location for a user.
+	 * @param userId - The user's unique identifier
+	 * @param location - The new location data
+	 * @throws {UserNotFoundError} If no source exists for the user
+	 */
+	updateUserLocation(userId: string, location: Location): void {
+		const source = this.sources.get(userId)
+		if (!source) {
+			throw new UserNotFoundError(userId)
+		}
+		source.pushLocation(location)
+	}
+
+	/**
+	 * Get last known location for a user.
+	 * @param userId - The user's unique identifier
+	 * @returns The last location, or null if none exists
+	 */
+	lastUserLocation(userId: string): Location | null {
+		return this.sources.get(userId)?.lastLocation ?? null
+	}
+
+	/**
+	 * Remove a user's LocationSource.
+	 * @param userId - The user's unique identifier
+	 */
+	removeUser(userId: string): void {
+		this.sources.delete(userId)
+	}
+}

apps/aris-backend/src/server.ts

@@ -1,6 +1,25 @@
+import { trpcServer } from "@hono/trpc-server"
 import { Hono } from "hono"
 
 import { registerAuthHandlers } from "./auth/http.ts"
+import { LocationService } from "./location/service.ts"
+import { createContext } from "./trpc/context.ts"
+import { createTRPCRouter } from "./trpc/router.ts"
+import { WeatherService } from "./weather/service.ts"
+
+function main() {
+	const locationService = new LocationService()
+
+	const weatherService = new WeatherService({
+		credentials: {
+			privateKey: process.env.WEATHERKIT_PRIVATE_KEY!,
+			keyId: process.env.WEATHERKIT_KEY_ID!,
+			teamId: process.env.WEATHERKIT_TEAM_ID!,
+			serviceId: process.env.WEATHERKIT_SERVICE_ID!,
+		},
+	})
+
+	const trpcRouter = createTRPCRouter({ locationService, weatherService })
 
 	const app = new Hono()
 
@@ -8,6 +27,19 @@ app.get("/health", (c) => c.json({ status: "ok" }))
 
 	registerAuthHandlers(app)
 
+	app.use(
+		"/trpc/*",
+		trpcServer({
+			router: trpcRouter,
+			createContext,
+		}),
+	)
+
+	return app
+}
+
+const app = main()
+
 export default {
 	port: 3000,
 	fetch: app.fetch,

apps/aris-backend/src/trpc/context.ts

@@ -0,0 +1,14 @@
+import type { FetchCreateContextFnOptions } from "@trpc/server/adapters/fetch"
+
+import { auth } from "../auth/index.ts"
+
+export async function createContext(opts: FetchCreateContextFnOptions) {
+	const session = await auth.api.getSession({ headers: opts.req.headers })
+
+	return {
+		user: session?.user ?? null,
+		session: session?.session ?? null,
+	}
+}
+
+export type Context = Awaited<ReturnType<typeof createContext>>

apps/aris-backend/src/trpc/router.ts

@@ -0,0 +1,50 @@
+import { initTRPC, TRPCError } from "@trpc/server"
+
+import type { LocationService } from "../location/service.ts"
+import type { WeatherService } from "../weather/service.ts"
+import type { Context } from "./context.ts"
+
+import { createLocationRouter } from "../location/router.ts"
+
+interface AuthedContext {
+	user: NonNullable<Context["user"]>
+	session: NonNullable<Context["session"]>
+}
+
+function createTRPC() {
+	const t = initTRPC.context<Context>().create()
+
+	const isAuthed = t.middleware(({ ctx, next }) => {
+		if (!ctx.user || !ctx.session) {
+			throw new TRPCError({ code: "UNAUTHORIZED" })
+		}
+		return next({
+			ctx: {
+				user: ctx.user,
+				session: ctx.session,
+			},
+		})
+	})
+
+	return {
+		router: t.router,
+		procedure: t.procedure.use(isAuthed),
+	}
+}
+
+export type TRPC = ReturnType<typeof createTRPC>
+
+export interface TRPCRouterDeps {
+	locationService: LocationService
+	weatherService: WeatherService
+}
+
+export function createTRPCRouter({ locationService }: TRPCRouterDeps) {
+	const t = createTRPC()
+
+	return t.router({
+		location: createLocationRouter(t, { locationService }),
+	})
+}
+
+export type TRPCRouter = ReturnType<typeof createTRPCRouter>

apps/aris-backend/src/weather/service.test.ts

@@ -0,0 +1,116 @@
+import type { Context } from "@aris/core"
+
+import { LocationKey } from "@aris/source-location"
+import {
+	Units,
+	WeatherFeedItemType,
+	type WeatherKitClient,
+	type WeatherKitResponse,
+} from "@aris/source-weatherkit"
+import { describe, expect, test } from "bun:test"
+
+import fixture from "../../../../packages/aris-source-weatherkit/fixtures/san-francisco.json"
+import { WeatherService } from "./service.ts"
+
+const mockClient = createMockClient(fixture.response as WeatherKitResponse)
+
+function createMockClient(response: WeatherKitResponse): WeatherKitClient {
+	return {
+		fetch: async () => response,
+	}
+}
+
+function createMockContext(location?: { lat: number; lng: number }): Context {
+	const ctx: Context = { time: new Date("2026-01-17T00:00:00Z") }
+	if (location) {
+		ctx[LocationKey] = { ...location, accuracy: 10, timestamp: new Date() }
+	}
+	return ctx
+}
+
+describe("WeatherService", () => {
+	test("feedSourceForUser creates source on first call", () => {
+		const service = new WeatherService({ client: mockClient })
+		const source = service.feedSourceForUser("user-1")
+
+		expect(source).toBeDefined()
+		expect(source.id).toBe("weather")
+	})
+
+	test("feedSourceForUser returns same source for same user", () => {
+		const service = new WeatherService({ client: mockClient })
+		const source1 = service.feedSourceForUser("user-1")
+		const source2 = service.feedSourceForUser("user-1")
+
+		expect(source1).toBe(source2)
+	})
+
+	test("feedSourceForUser returns different sources for different users", () => {
+		const service = new WeatherService({ client: mockClient })
+		const source1 = service.feedSourceForUser("user-1")
+		const source2 = service.feedSourceForUser("user-2")
+
+		expect(source1).not.toBe(source2)
+	})
+
+	test("feedSourceForUser applies hourly and daily limits", async () => {
+		const service = new WeatherService({
+			client: mockClient,
+			hourlyLimit: 3,
+			dailyLimit: 2,
+		})
+		const source = service.feedSourceForUser("user-1")
+		const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+
+		const items = await source.fetchItems(context)
+
+		const hourly = items.filter((i) => i.type === WeatherFeedItemType.hourly)
+		const daily = items.filter((i) => i.type === WeatherFeedItemType.daily)
+
+		expect(hourly).toHaveLength(3)
+		expect(daily).toHaveLength(2)
+	})
+
+	test("feedSourceForUser applies units", async () => {
+		const service = new WeatherService({
+			client: mockClient,
+			units: Units.imperial,
+		})
+		const source = service.feedSourceForUser("user-1")
+		const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+
+		const items = await source.fetchItems(context)
+		const current = items.find((i) => i.type === WeatherFeedItemType.current)
+
+		expect(current).toBeDefined()
+		// Fixture has ~15.87°C, imperial should be ~60.6°F
+		expect(current!.data.temperature).toBeGreaterThan(50)
+	})
+
+	test("removeUser removes the source", () => {
+		const service = new WeatherService({ client: mockClient })
+		service.feedSourceForUser("user-1")
+
+		service.removeUser("user-1")
+
+		// After removal, feedSourceForUser should create a new instance
+		const source2 = service.feedSourceForUser("user-1")
+		expect(source2).toBeDefined()
+	})
+
+	test("removeUser allows new source to be created", () => {
+		const service = new WeatherService({ client: mockClient })
+		const source1 = service.feedSourceForUser("user-1")
+
+		service.removeUser("user-1")
+		const source2 = service.feedSourceForUser("user-1")
+
+		expect(source1).not.toBe(source2)
+	})
+
+	test("removeUser is no-op for unknown user", () => {
+		const service = new WeatherService({ client: mockClient })
+
+		expect(() => service.removeUser("unknown")).not.toThrow()
+	})
+})

apps/aris-backend/src/weather/service.ts

@@ -0,0 +1,40 @@
+import { WeatherSource, type WeatherSourceOptions } from "@aris/source-weatherkit"
+
+import type { FeedSourceProvider } from "../feed/service.ts"
+
+/**
+ * Options forwarded to every per-user WeatherSource.
+ * Must include either `credentials` or `client` (same requirement as WeatherSourceOptions).
+ */
+export type WeatherServiceOptions = WeatherSourceOptions
+
+/**
+ * Manages WeatherSource instances per user.
+ */
+export class WeatherService implements FeedSourceProvider {
+	private sources = new Map<string, WeatherSource>()
+	private readonly options: WeatherServiceOptions
+
+	constructor(options: WeatherServiceOptions) {
+		this.options = options
+	}
+
+	/**
+	 * Get or create a WeatherSource for a user.
+	 */
+	feedSourceForUser(userId: string): WeatherSource {
+		let source = this.sources.get(userId)
+		if (!source) {
+			source = new WeatherSource(this.options)
+			this.sources.set(userId, source)
+		}
+		return source
+	}
+
+	/**
+	 * Remove a user's WeatherSource.
+	 */
+	removeUser(userId: string): void {
+		this.sources.delete(userId)
+	}
+}

bun.lock

@@ -20,6 +20,9 @@
         "@aris/core": "workspace:*",
         "@aris/source-location": "workspace:*",
         "@aris/source-weatherkit": "workspace:*",
+        "@hono/trpc-server": "^0.3",
+        "@trpc/server": "^11",
+        "arktype": "^2.1.29",
         "better-auth": "^1",
         "hono": "^4",
         "pg": "^8",
@@ -91,6 +94,8 @@
 
     "@better-fetch/fetch": ["@better-fetch/fetch@1.1.21", "", {}, "sha512-/ImESw0sskqlVR94jB+5+Pxjf+xBwDZF/N5+y2/q4EqD7IARUTSpPfIo8uf39SYpCxyOCtbyYpUrZ3F/k0zT4A=="],
 
+    "@hono/trpc-server": ["@hono/trpc-server@0.3.4", "", { "peerDependencies": { "@trpc/server": "^10.10.0 || >11.0.0-rc", "hono": ">=4.*" } }, "sha512-xFOPjUPnII70FgicDzOJy1ufIoBTu8eF578zGiDOrYOrYN8CJe140s9buzuPkX+SwJRYK8LjEBHywqZtxdm8aA=="],
+
     "@noble/ciphers": ["@noble/ciphers@2.1.1", "", {}, "sha512-bysYuiVfhxNJuldNXlFEitTVdNnYUc+XNJZd7Qm2a5j1vZHgY+fazadNFWFaMK/2vye0JVlxV3gHmC0WDfAOQw=="],
 
     "@noble/hashes": ["@noble/hashes@2.0.1", "", {}, "sha512-XlOlEbQcE9fmuXxrVTXCTlG2nlRXa9Rj3rr5Ue/+tX+nmkgbX720YHh0VR3hBF9xDvwnb8D2shVGOwNx+ulArw=="],
@@ -129,6 +134,8 @@
 
     "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
 
+    "@trpc/server": ["@trpc/server@11.8.1", "", { "peerDependencies": { "typescript": ">=5.7.2" } }, "sha512-P4rzZRpEL7zDFgjxK65IdyH0e41FMFfTkQkuq0BA5tKcr7E6v9/v38DEklCpoDN6sPiB1Sigy/PUEzHENhswDA=="],
+
     "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
 
     "@types/node": ["@types/node@25.0.9", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-/rpCXHlCWeqClNBwUhDcusJxXYDjZTyE8v5oTO7WbL8eij2nKhUeU89/6xgjU7N4/Vh3He0BtyhJdQbDyhiXAw=="],

docs/backend-spec.md

@@ -7,12 +7,14 @@ ARIS needs a backend service that manages per-user FeedEngine instances and deli
 ## Requirements
 
 ### Authentication
+
 - Email/password authentication using BetterAuth
 - PostgreSQL for session and user storage
 - Session tokens validated via `Authorization: Bearer <token>` header
 - Auth endpoints exposed via BetterAuth's built-in routes
 
 ### FeedEngine Management
+
 - Each authenticated user gets their own FeedEngine instance
 - Instances are cached in memory with a 30-minute TTL
 - TTL resets on any activity (WebSocket message, location update)
@@ -20,6 +22,7 @@ ARIS needs a backend service that manages per-user FeedEngine instances and deli
 - Source configuration is hardcoded initially (customization deferred)
 
 ### WebSocket Connection
+
 - Single endpoint: `GET /ws` (upgrades to WebSocket)
 - Authentication via `Authorization: Bearer <token>` header on upgrade request
 - Rejected before upgrade if token is invalid
@@ -28,20 +31,24 @@ ARIS needs a backend service that manages per-user FeedEngine instances and deli
 - On connect: immediately send current feed state
 
 ### JSON-RPC Protocol
+
 All WebSocket communication uses JSON-RPC 2.0.
 
 **Client → Server (Requests):**
+
 ```json
 { "jsonrpc": "2.0", "method": "location.update", "params": { "lat": 51.5, "lng": -0.1, "accuracy": 10, "timestamp": "2025-01-01T12:00:00Z" }, "id": 1 }
 { "jsonrpc": "2.0", "method": "feed.refresh", "params": {}, "id": 2 }
 ```
 
 **Server → Client (Responses):**
+
 ```json
 { "jsonrpc": "2.0", "result": { "ok": true }, "id": 1 }
 ```
 
 **Server → Client (Notifications - no id):**
+
 ```json
 { "jsonrpc": "2.0", "method": "feed.update", "params": { "items": [...], "errors": [...] } }
 ```
@@ -49,18 +56,19 @@ All WebSocket communication uses JSON-RPC 2.0.
 ### JSON-RPC Methods
 
 | Method            | Params                              | Description                                 |
-|--------|--------|-------------|
+| ----------------- | ----------------------------------- | ------------------------------------------- |
 | `location.update` | `{ lat, lng, accuracy, timestamp }` | Push location update, triggers feed refresh |
 | `feed.refresh`    | `{}`                                | Force manual feed refresh                   |
 
 ### Server Notifications
 
 | Method        | Params                       | Description            |
-|--------|--------|-------------|
+| ------------- | ---------------------------- | ---------------------- |
 | `feed.update` | `{ context, items, errors }` | Feed state changed     |
 | `error`       | `{ code, message, data? }`   | Source or system error |
 
 ### Error Handling
+
 - Source failures during refresh are reported via `error` notification
 - Format: `{ "jsonrpc": "2.0", "method": "error", "params": { "code": -32000, "message": "...", "data": { "sourceId": "weather" } } }`
 
@@ -96,16 +104,19 @@ All WebSocket communication uses JSON-RPC 2.0.
 ## Implementation Approach
 
 ### Phase 1: Project Setup
+
 1. Create `apps/aris-backend` with Hono
 2. Configure TypeScript, add dependencies (hono, better-auth, postgres driver)
 3. Set up database connection and BetterAuth
 
 ### Phase 2: Authentication
+
 4. Configure BetterAuth with email/password provider
 5. Mount BetterAuth routes at `/api/auth/*`
 6. Create session validation helper for extracting user from token
 
 ### Phase 3: FeedEngine Manager
+
 7. Create `FeedEngineManager` class:
    - `getOrCreate(userId): FeedEngine` - returns cached or creates new
    - `touch(userId)` - resets TTL
@@ -114,22 +125,26 @@ All WebSocket communication uses JSON-RPC 2.0.
 8. Factory function to create FeedEngine with default sources
 
 ### Phase 4: WebSocket Handler
+
 9. Create WebSocket upgrade endpoint at `/ws`
 10. Validate `Authorization` header before upgrade
 11. On connect: register connection, send initial feed state
 12. On disconnect: unregister connection
 
 ### Phase 5: JSON-RPC Handler
+
 13. Create JSON-RPC message parser and dispatcher
 14. Implement `location.update` method
 15. Implement `feed.refresh` method
 16. Wire FeedEngine subscription to broadcast `feed.update` to all user connections
 
 ### Phase 6: Connection Manager
+
 17. Create `ConnectionManager` to track WebSocket connections per user
 18. Broadcast helper to send to all connections for a user
 
 ### Phase 7: Integration & Testing
+
 19. Integration test: auth → connect → location update → receive feed
 20. Test multiple connections receive same updates
 21. Test TTL cleanup