UPD: initial architecture

docs/architecture.md

@@ -0,0 +1,14 @@
+# Architecture
+
+Beacon is a single Next.js deployment connected to PostgreSQL. Presentation (`src/app`, `src/components`) calls server application modules; repositories in `src/features/*/repositories` are the only path to Drizzle. Domain language remains `Recommendation`, `Workspace` and `MediaItem`; “Beacon” is presentation branding.
+
+```text
+Browser → App Router → server guard/use case → repository → Drizzle → PostgreSQL
+                         ↘ metadata provider contract (future)
+```
+
+Server Components are the default. Client Components are limited to theme selection, mobile active navigation and the login form. Better Auth owns credential hashing and session cookies. `requireUser`, `requireWorkspaceMember` and `requireWorkspaceRole` validate authorization on the server; middleware is only an early redirect optimization.
+
+Errors use typed application errors and route handlers map them to safe HTTP responses. Pino redacts secrets. Environment is parsed by Zod at startup. Tests use Vitest for unit contracts; integration tests are reserved for a PostgreSQL test database and Playwright covers browser routing. UI strings are presently English and concentrated in components/configuration; a dedicated i18n library is intentionally deferred.
+
+External metadata adapters normalize results to `MediaSearchResult` and `MediaDetails`; raw provider responses never cross the application boundary. The cache table is ready for future use.

docs/decisions/0001-initial-architecture.md

@@ -0,0 +1,11 @@
+# ADR 0001: Initial architecture
+
+## Decision
+
+Use a modular Next.js monolith with PostgreSQL, Drizzle and Better Auth. Model workspaces from the start and use explicit workspace paths. Keep metadata suppliers behind adapters.
+
+## Rationale
+
+The expected scale is a small private community, so a single deployable is simpler to operate and evolve. PostgreSQL gives transactional constraints for memberships and recommendations. Drizzle provides reviewed SQL migrations without schema synchronization in production. Better Auth provides password and session primitives without a mandatory cloud service.
+
+No Redis, queues or microservices are introduced: no demonstrated workload requires them. A future worker can consume the same database and provider contracts without changing the web application's domain model.

docs/domain-model.md

@@ -0,0 +1,9 @@
+# Domain model
+
+`User` is an authenticated account. A `Workspace` is a community and `WorkspaceMember` assigns its ADMIN or MEMBER role. A user may be in multiple workspaces.
+
+`MediaItem` is one external or manual work. Manual works use `MANUAL` plus an application-generated external identifier. A `Recommendation` is the one active personal recommendation for a media item in a workspace; its uniqueness is `(workspaceId, mediaItemId)`. `RecommendationStatus` is per user and recommendation, while reactions and comments reinforce the existing recommendation instead of duplicating it.
+
+Provider/external ID identifies media globally. A work can appear in different workspaces. Soft deletion is available for recommendations and comments. Invitation tokens are stored hashed. Audit metadata is deliberately non-sensitive.
+
+Status values are PENDING, INTERESTED, IN_PROGRESS, COMPLETED, DROPPED and NOT_INTERESTED. Strength values NORMAL, HIGH and MUST_EXPERIENCE express insistence, not quality. Ratings are optional and intended for completed works.