openchatui/openchat

1. Overall shape

- This is a Next.js App Router application with a strong separation between UI pages, API routes, domain services, and database access.

- The product is an AI workspace rather than a single chat UI: chat, models, drive/docs, audio, video, web search, code execution, users/groups, and admin configuration all live in the same runtime.

2. Frontend presentation layer

- Routes under app/(auth) and app/(main) define the visible app surfaces: login/signup, the main chat area, archive, search, settings, drive, and the admin console.

- Most screens are composed from components/*, with large feature folders such as components/chat, components/drive, components/admin, components/search, and components/docs.

- This layer is primarily presentational and interactive; it does not own business logic.

3. Client-side data access

- Feature hooks in hooks/* are the main bridge from UI to backend, e.g. chat streaming, drive file lists, pinned models, users, tags, connections, audio, and admin settings.

- Those hooks call small API client wrappers in lib/api/*, which centralize HTTP requests and response typing.

- In architecture terms, the browser talks to the app through these hooks, not directly to domain services.

4. Backend API boundary

- The primary backend surface is app/api/v1/*, organized by domain: chats, models, users, groups, drive, audio, video, websearch, code, connections, and activity.

- There is also app/api/auth/[...nextauth] for session-based authentication, plus app/api/docs/* for Swagger/OpenAPI docs.

- These route handlers are the API entry points that connect external clients, the frontend, and the domain layer.

5. Domain/service layer

- Core behavior lives in lib/modules/*, which is split by capability:

- chat for chat orchestration and client/store logic

- ai and tools for provider/tool abstractions

- drive for document/file sync and storage abstraction

- search for search orchestration

- audio, web-browsing, image-generation, video-generation, and pyodide for specialized AI features

- access-control for permissions and model access rules

- This layer is where the app’s feature logic is concentrated, and it sits between API handlers and persistence/providers.

6. Persistence layer

- Database access is isolated in lib/db/*, with separate modules for chats, users, groups, models, api keys, configs, connections, drive, images, video, websearch, and code.

- Prisma is the ORM, with separate schemas for SQLite and PostgreSQL under prisma/, plus a long migration history that reflects the product’s growing feature set.

- The repo is clearly designed to support both local self-hosted SQLite and production PostgreSQL.

7. Authentication, authorization, and identity

- Authentication is session-based through NextAuth-style routes and services under lib/auth/*.

- Authorization is not just “logged in / logged out”: there are roles, groups, permissions, API keys, and per-model access controls.

- The admin area and several API endpoints are protected by middleware and authz services, making identity a first-class architectural boundary.

8. AI provider and tool integration

- The app is provider-agnostic at the core: lib/modules/ai/providers and lib/modules/tools/* adapt to external AI services.

- Material external integrations include OpenAI, Ollama, Google Drive, Deepgram, ElevenLabs, Browserless/Browserbase-style web browsing, and Google PSE.

- These integrations are exposed through feature-specific APIs and admin configuration screens, so provider wiring is a runtime concern rather than hardcoded application logic.

9. Chat subsystem

- Chat is a major domain with dedicated pages, components, hooks, and server APIs.

- The flow is: user input in chat UI → streaming/chat hooks → /api/v1/chat* and /api/v1/chats* endpoints → chat service and persistence.

- Features around chat include attachments, titles, archives, model selection, prompt suggestions, live activity, and message history.

10. Drive and documents subsystem

- Drive is its own product area with folder/file browsing, upload/download, preview, star/trash/restore, search, and sync.

- The backend separates file/folder operations from provider sync/configuration, allowing either Google Drive or local document storage behavior.

- The UI includes rich file previews for PDFs, Office docs, images, videos, CSVs, and folder navigation, so the architecture treats files as first-class managed content.

11. Admin and configuration surfaces

- app/(main)/admin and components/admin/* form a centralized control plane for models, connections, users, groups, UI settings, audio, image, video, code interpreter, web search, and drive.

- Many admin screens correspond directly to config endpoints under app/api/v1/*/config and */config/update.

- This suggests a “configure everything from inside the app” architecture, where runtime behavior is controlled through persisted settings.

12. Supporting features and auxiliary systems

- There are dedicated surfaces for search, archive, settings, activity tracking (heartbeat, active users), public files/images/profiles routes, and setup/bootstrap.

- Swagger docs are built into the app, which makes the REST API a deliberate part of the product surface, not just an internal implementation detail.

- A separate scripts/ area includes tooling for browser automation tests and collaborative editing support, indicating some features rely on additional runtime processes beyond the main Next.js server.

13. Key architectural diagram takeaway

- A useful diagram should show:

- Browser/UI layers on the left

- Next.js pages and route handlers in the middle

- Domain services/modules and DB access below

- External AI/content providers on the right

- Prisma-backed SQLite/PostgreSQL persistence at the bottom

- The main data flow is UI → hooks/API client → REST route → service/module → DB or external provider → response back to UI.