zamelane/lophius

Purpose and topology

Lophius is a Bun/TypeScript monorepo for collecting, curating, searching, and tracking media. It has three deployable surfaces: the user-facing Next.js application, a separate plugin-driven metadata worker, and a Next.js documentation site. Shared persistence is a database package.

• apps/web/app/layout.tsx

• apps/worker/src/index.ts

• packages/database/src/index.ts

Web application entry and routing

The primary runtime is a localized Next.js App Router application. Language-scoped routes divide authentication/configuration from the authenticated media workspace, including media-type pages, calendars, lists, profiles, settings, and administration. Middleware, instrumentation, and a custom server form the HTTP/runtime boundary.

• apps/web/app/[lang]/(home)/layout.tsx

• apps/web/app/[lang]/(home)/[mediaType]/page.tsx

• apps/web/middleware.ts

• apps/web/server.ts

Identity, startup, and configuration

Authentication is implemented as feature services with validation schemas and session/shared auth state. A configuration wizard provisions an administrator, database connection/schema, environment, and reload flow; startup code seeds/initializes application state. This is the operational boundary before normal user workflows are available.

• apps/web/src/features/auth/services/login.tsx

• apps/web/src/processes/configuration/view.tsx

• apps/web/src/features/configuration/services/database-push.ts

• apps/web/src/shared/lib/startup/index.ts

Media domain and persistence

packages/database centralizes Drizzle configuration, schemas, model repositories, and services. Its core model is media linked to types, status, votes, budgets/revenue, contributors, taxonomy, translations, release dates, sources, and external artwork. Web features and worker plugins should use this package rather than define independent persistence mappings.

• packages/database/src/schemas/medias.ts

• packages/database/src/models/Media/repository.ts

• packages/database/src/services/UnitOfWorks.ts

• packages/database/drizzle.config.ts

Media interaction flows

The web app reads media details and lists from local storage, lets users organize items into lists, and presents calendar/activity views. Search has offline and online modes, with language prioritization; online work crosses to the worker through a WebSocket-oriented client hook. Route handlers expose selected user, asset, and Open Graph endpoints.

• apps/web/src/features/media/search/search/index.tsx

• apps/web/src/features/online-search/hooks/useSearchWebSocket.tsx

• apps/web/src/features/media-list-button/services/addToList.ts

• apps/web/app/api/assets/route.ts

Worker and metadata-ingestion pipeline

The worker is an independent server that loads/manages plugins, queues searches, stores plugin state, and publishes parse status over WebSocket. Its TMDB plugin calls the TMDB API, runs staged pipelines to obtain details, images, people, translations, and recommendations, persists normalized data, and emits incremental status/data events. Rate limiting and DNS-agent utilities protect outbound integration calls.

• apps/worker/src/server-app.ts

• apps/worker/src/plugin-loader.ts

• apps/worker/src/search/search-queue.ts

• apps/worker/plugins/tmdb/plugin.ts

• apps/worker/plugins/tmdb/steps/details/index.ts

Presentation, localization, and documentation

The web client is organized around feature/widget/shared layers, with SWR, theme, and auth providers; locale messages support eight languages. apps/docs is a separate Next.js/MDX documentation application, not part of the production media workflow.

• apps/web/src/shared/providers/SWRProvider.tsx

• apps/web/src/shared/i18n/config.ts

• apps/web/src/widgets/media/page-info/view.tsx

• apps/docs/app/[[...mdxPath]]/page.jsx