Next.js Web Application
Relevant source files
The following files were used as context for generating this wiki page:
The Next.js Web Application serves as the primary user interface for the ATMOS workspace. It is a modern, AI-first web application designed to provide a comprehensive environment for project management, documentation, and terminal interaction. The application utilizes the Next.js App Router for routing and layouts, integrating deeply with a backend service via WebSocket and REST APIs.
Within the broader project architecture, the web application acts as the presentation layer (Layer 3 in the documentation hierarchy), consuming shared UI components from @workspace/ui and aligning its data structures with Rust-based backend DTOs.
Sources: apps/web/AGENTS.md:1-5, DOCUMENTATION.md:23-45
Architecture and Directory Structure
The application follows a standard Next.js directory structure, optimized for scalability and type safety. Key logic is separated into API clients, React hooks, and business-specific components.
Core Directory Layout
| Path | Purpose |
|---|---|
src/app/ | Next.js App Router containing pages and layouts. |
src/components/ | Business-specific UI components (e.g., WikiContent). |
src/hooks/ | Custom React hooks for client-side state and logic. |
src/api/ | Centralized API client layer for REST and WebSocket interactions. |
src/types/api.ts | TypeScript definitions strictly aligned with backend DTOs. |
src/proxy.ts | Utilities for API route proxying. |
Sources: apps/web/AGENTS.md:8-20, apps/landing/README.md:27-55
Component Interaction Flow
The following diagram illustrates how the frontend components interact with centralized stores and the backend API.
This structure ensures that components do not manually use fetch() or axios(), instead relying on a controlled API layer.
Sources: apps/web/AGENTS.md:23-28, specs/tech/project-wiki.md:214-239
Wiki Integration System
A significant feature of the web application is the integrated Project Wiki, which provides a research-grade documentation viewer directly within the workspace.
Wiki Viewer Architecture
The Wiki system is implemented using a 3-column resizable layout, managed by react-resizable-panels. It consists of a navigation tree, a main content area with Markdown rendering, and a heading-based Table of Contents.
Content Rendering and Editing
The WikiContent component handles the display and modification of Markdown files. It supports two primary modes: Preview and Edit.
- Preview Mode: Uses
MarkdownRendererto display formatted text and renders Mermaid diagrams lazily. It also parses YAML frontmatter to display metadata like reading time and difficulty level. - Edit Mode: Integrates the
MonacoEditorfor direct manipulation of the Markdown source.
Sources: apps/web/src/components/wiki/WikiContent.tsx:100-115, apps/web/src/components/wiki/WikiContent.tsx:290-320
Technical Implementation Details
The Wiki system relies on a Zustand store (use-wiki-store.ts) to manage state across sessions, including catalog loading and active page content.
Working Guidelines and Design Principles
The application enforces strict design and coding standards to ensure consistency across the workspace.
UI and Theming
The application uses a semantic color system to support both Light and Dark modes. Developers are instructed to use CSS variables rather than hardcoded Tailwind colors.
| Variable | Usage |
|---|---|
bg-background | Main application background. |
text-foreground | Primary text color. |
border-border | Standard border color. |
bg-accent | Highlighted or active states. |
Sources: apps/web/AGENTS.md:33-42
API Interaction Rules
- Type Safety: All responses must strictly match Rust DTOs defined in
apps/api/src/api/dto.rs. - Centralization: All network requests must use the centralized
client.tsorws-api.ts. - Server Components: Prefer Next.js Server Components for data fetching where client-side interactivity is not required.
Sources: apps/web/AGENTS.md:23-31
Conclusion
The Next.js Web Application is a highly structured frontend that centralizes complex workspace operations into an accessible interface. By leveraging a modular architecture, strict type alignment with the backend, and integrated features like the Project Wiki and Terminal, it provides a robust environment for ATMOS users.
Sources: DOCUMENTATION.md:1-15, apps/web/AGENTS.md:1-5