Arda Frontend Application Architecture

1. System Overview

The Arda Frontend Application is a web interface built to interact with the Arda System. It is designed to provide a responsive, secure, and intuitive user experience for managing items, orders, and kanban workflows.

The application is built using Next.js (App Router), TypeScript, and Tailwind CSS. It serves as the frontend interface for the Arda system, interacting with backend services via a robust API layer and providing a rich user experience through a component-based architecture.

Technology Stack

Component	Technology	Version	Purpose
Framework	Next.js	15.3.2	Core application framework (App Router)
Language	TypeScript	5.x	Static typing and developer tooling
UI Library	React	19.x	Component-based UI rendering
Styling	Tailwind CSS	4.x	Utility-first CSS framework
Components	Radix UI	-	Headless, accessible UI primitives (via shadcn/ui)
State	React Context	-	Global state (Auth, UI preferences)
Auth	AWS Cognito	v3 SDK	Identity and Access Management

2. Architectural Patterns

2.1 Next.js App Router

The application utilizes the Next.js App Router (src/app), leveraging React Server Components (RSC) by default. This structure allows for:

• Nested Layouts: layout.tsx files handle shared UI (sidebars, headers) across routes.
• Route Groups: Directories like (auth) or functional groupings organize code without affecting URL paths.
• Server-Side Rendering (SSR): Initial page loads are optimized for performance.

2.2 Backend-for-Frontend (BFF)

The application implements a BFF pattern using Next.js API Routes (src/app/api/...).

• Proxy Role: The frontend client (browser) rarely calls the downstream Arda services directly. Instead, it calls its own local API.
• Security Boundary: The local API routes attach sensitive credentials (like the ARDA_API_KEY) and enriched context headers (X-Tenant-Id, X-Author) before forwarding requests upstream.
• Token Handling: JWT handling and validation are centralized here.

2.3 Security & Authentication

Authentication is a shared responsibility between the Client, the BFF, and AWS Cognito.

1. Client-Side (AuthContext):
   * Manages the user session.
   * Stores accessToken and idToken in localStorage.
   * Handles Cognito flows: Sign In, Password Reset, Challenge Response.
2. Transit:
   * Requests to /api/arda/... include the Authorization: Bearer <accessToken> header.
3. BFF Layer (route.ts):
   * Validates the incoming JWT structure.
   * Extracts claims (User ID, Tenant ID) to form trusted headers.
   * Signs the upstream request with the system’s ARDA_API_KEY.

3. Key Core Components

3.1 Authentication Context (src/contexts/AuthContext.tsx)

This context is the heart of client-side security. It provides:

• user: The current authenticated user object.
• refreshTokens(): Logic to proactively refresh expired AWS Cognito tokens.
• checkAuth(): Validates local tokens on application mount.

3.2 Arda Client (src/lib/ardaClient.ts)

A centralized, typed HTTP client wrapper.

• Purpose: Abstracts fetch calls to the local BFF API.
• getAuthHeaders(): Automatically injects valid tokens into requests. It checks token expiration and attempts a refresh if necessary before making the call.
• handleApiResponse<T>(): Standardizes error parsing, handling standard HTTP errors and specific Arda API error formats JSON/text.

3.3 API Route Handlers (src/app/api/.../route.ts)

These handlers serve as the secure gateway. A typical handler:

1. Authenticates: Calls processJWTForArda(request) to verify the user.
2. Transforms: Reads the request body or parameters.
3. Forwards: Constructs a request to ${env.BASE_URL} with:
   * Authorization: Bearer ${env.ARDA_API_KEY}
   * X-Author: User’s ID from JWT.
   * X-Tenant-Id: Tenant ID from JWT.

4. Feature Implementation Examples

4.1 BFF Request Flow

The following sequence diagram illustrates the flow of creating an item, demonstrating the security context propagation.

4.2 UI Structure & Design

• Component Composition: Features are built using atomic components from src/components/ui (buttons, inputs) combined into molecule-level domain components (e.g., CardStateDropdown).
• Styling Strategy: Tailwind CSS is used exclusively.
  * Global styles in globals.css.
  * Component styles via utility classes (e.g., className="flex items-center p-4").
  * Dark mode support via next-themes and Tailwind’s dark: modifier.

5. Project Structure Reference

The following tree highlights the architectural significance of key directories.

src/
├── app/                        # Next.js App Router (Routes & API)
│   ├── api/                    # BFF API Layer
│   │   ├── arda/               # Proxy routes for Arda Backend
│   │   └── auth/               # Auth related endpoints
│   ├── (routes)/               # Page routes (dashboard, items, etc.)
│   └── layout.tsx              # Root layout (Providers, Global CSS)
├── components/
│   ├── ui/                     # Reusable primitives (shadcn/ui)
│   │   └── button.tsx
│   ├── common/                 # Shared domain components
│   │   └── app-header.tsx
│   └── [feature]/              # Feature-specific components
│       └── items/
├── contexts/                   # Global State (Auth, UI)
├── lib/                        # Core Utilities
│   ├── ardaClient.ts           # Typed API Client
│   ├── jwt.ts                  # Token processing logic
│   └── utils.ts                # General helpers
└── types/                      # TypeScript Definitions
    ├── arda-api.ts             # API Request/Response shapes
    └── [domain].ts             # Entity definitions (items, kanban)

Repository Root

The root directory contains project configuration files and documentation.

• Configuration Files:
  • package.json & package-lock.json: Define project dependencies and scripts. The project relies on React, Next.js, Radix UI (via shadcn/ui patterns), and various utility libraries.
  • tsconfig.json: TypeScript configuration.
  • tailwind.config.js & postcss.config.js: Styling configuration using Tailwind CSS.
  • next.config.ts: Next.js specific configuration.
  • jest.config.js & jest.setup.ts: Testing configuration using Jest.
  • .eslintrc.json (or similar): Linting rules (assumed based on standard practice, though eslint.config.mjs was present).
• Documentation:
  • README.md: General entry point.
  • CHANGELOG.md: Tracks version history.
  • PERFORMANCE_OPTIMIZATION_REPORT.md & PERFORMANCE_TEST_GUIDE.md: Documentation related to performance analysis and testing standards.
  • JWT_LOGGING_GUIDE.md: Guidelines for handling JWT logging.

Source Code Structure (src/)

The core application logic resides in the src directory, organized into functional areas following Next.js App Router conventions and clean architecture principles.

src/app

This directory contains the application routes (Next.js App Router) and API endpoints. Each directory generally corresponds to a URL path.

src/app (Root)

Contains the global layout.tsx which defines the root HTML structure and global providers (e.g., Auth, Toast), and page.tsx which typically renders the landing page or redirects to the main dashboard. globals.css defines global Tailwind styles and CSS variables.

src/app/account-profile

Manages the user’s account profile view. This directory likely contains a page for displaying and editing user details, such as name, email, and preferences.

src/app/api

This directory houses the backend-for-frontend (BFF) API routes. These routes act as a proxy or orchestration layer between the frontend client and the backend services.

• src/app/api/arda: The primary namespace for Arda-specific domain operations.
  * .../items: Endpoints for item management (CRUD, searching, uploading). Subdirectories likely handle specific item operations like upload-job, upload-status, and retrieving individual items by ID.
  * .../kanban: Endpoints for the Kanban system. Includes routes for card management (kanban-card) such as creating, updating, moving, and querying cards by status or item.
  * .../tenant: Endpoints for tenant-related operations, potentially including context switching or agent-for functionalities.
  * .../user-account: Endpoints for user account management tasks.
• src/app/api/auth: Handles authentication flows, likely engaging with AWS Cognito or a similar provider. Includes sub-routes for things like secret-hash.
• src/app/api/debug: Utilities for debugging the application state or environment configuration.
• src/app/api/email: Handles email sending functionality, such as order notifications.

src/app/blogs

Contains the blog section of the application. It likely uses dynamic routing (e.g., [slug]) to render individual blog posts fetched from a content source (like HubSpot or a CMS).

src/app/company-settings

Provides the interface for managing company-level settings. This likely allows administrators to configure tenant-wide preferences and defaults.

src/app/dashboard

The main landing view for authenticated users. This directory contains the implementation of the dashboard, which typically aggregates key metrics or shortcuts to other parts of the system.

src/app/help

Implements the help center or support section. It may include dynamic routes for different help articles or sections.

src/app/input-demo

A demonstration or testing area for input components, likely used during development to verify form behaviors and styles.

src/app/items

The main interface for the Item Master. This directory contains the page for listing, searching, and viewing details of items in the inventory or catalog.

src/app/items-grid-test

A test or experimental page for the items grid implementation, separating experimental layouts from the production items page.

src/app/kanban

The Kanban board interface. This directory implements the drag-and-drop board view for visualizing and managing workflow items (cards).

src/app/mobile-device-check

A utility page or redirect logic to handling users accessing the application from mobile devices, potentially enforcing platform restrictions or guiding them to a mobile-optimized view.

src/app/order-queue

Manages the order queue interface. This view likely lists incoming or processing orders that need attention.

src/app/receiving

The interface for receiving goods. This page allows users to process incoming inventory or shipments.

src/app/reset-password

Handles the password reset flow.

• .../email-sent: The confirmation page shown after a reset link has been requested.
• .../new: The page where the user enters a new password (often with a token).
• .../success: The success message page after a password has been changed.

src/app/scan

The interface for scanning tasks, such as QR code or barcode scanning functionality for inventory or lookup purposes.

src/app/settings

General user settings page, likely covering preferences not strictly tied to the account profile or company settings.

src/app/signin

The implementation of the sign-in page, including the login form and integration with the authentication context.

src/app/signup

The implementation of the sign-up page for new user registration.

• .../success: The page displayed after successful registration.

src/app/simple-grid-test

Another testing layout for grid components, likely simpler than the main items grid.

src/components

This directory contains React components, organized by scope and reusability.

src/components/common

Contains shared, domain-specific components used across multiple features. Examples include AppHeader.tsx, custom modals like DeleteConfirmationModal.tsx, and specialized inputs like PasswordInput.tsx.

• .../Button: Likely contains specialized or wrapper button components (e.g., CardButton).
• .../card-state: Components specifically for displaying or managing card states (e.g., CardStateDisplay).

src/components/examples

Contains example usage or demo components, possibly used in the input-demo or other test pages.

src/components/homepage

Components specific to the homepage or landing page layout.

src/components/items

Components dedicated to the items feature, such as item lists, detail views, or grid cells specific to item data.

src/components/scan

Components used in the scan feature, likely including the camera interface or scanner input handling.

src/components/settings

Components specific to the settings pages, such as configuration forms or toggle sections.

src/components/sideBar

Components implementing the application sidebar navigation. This includes the sidebar structure and links.

src/components/signIn

Components specific to the sign-in flow, such as the login form layout.

src/components/table

Components related to data table rendering, possibly abstractions over HTML tables or a data-grid library.

src/components/ui

This directory houses low-level, reusable UI primitives, often following the shadcn/ui pattern. It includes foundational elements like button.tsx, input.tsx, dialog.tsx, dropdown-menu.tsx, etc.

• .../__tests__: Tests specifically for these UI components.

src/constants

Defines application-wide constants.

• constants.ts: General static values like page limits, default timeouts, or configuration keys.
• interfaces.ts & types.ts: Define interfaces and types specifically related to these constants or simple shared structures.

src/contexts

Contains React Context Providers for global state management.

• AuthContext.tsx: Manages user authentication state and session data.
• JWTContext.tsx: Handles JWT storage and access.
• OrderQueueContext.tsx: Manages state for the order queue feature.
• SidebarVisibilityContext.tsx: Controls the visibility state of the sidebar.

src/hooks

Use-case specific custom React hooks.

• useAuthValidation.ts: Logic for validating authentication state.
• useFormValidation.ts: Helpers for form validation logic.
• use-mobile.ts: Hook to detect mobile viewports.
• useSidebarState.ts: Logic for sidebar toggling.

src/lambda

Contains serverless function code, likely for AWS Lambda triggers associated with Cognito.

• .../auto-confirm-cognito-user: Logic to automatically confirm users in Cognito under certain conditions.
• .../cognito-custom-forgot-password-message: Customizes the content of the password reset email sent by Cognito.

src/lib

Contains core utility libraries and business logic helpers.

• ardaClient.ts: The main API client wrapper for interacting with Arda backend services.
• hubspot.ts & hubspot-knowledge.ts: Integration logic for HubSpot (CMR/Knowledge base).
• jwt.ts: Utilities for parsing and managing JSON Web Tokens.
• mappers: Directory for data mapping functions (transforming API responses to frontend models).

src/tests

Contains integration and unit tests for the application.

• Tests are often named after the feature they test (e.g., signin.test.tsx, items.test.tsx).
• .../mocks: Contains mock data or mock implementations used across tests.

src/types

Contains TypeScript type definitions covering the domain model.

• arda-api.ts: Types defining the structure of API requests and responses.
• items.ts, kanban.ts, tenant.ts, user-account.ts: Domain entities reflecting the business objects (Items, Kanban Cards, Tenants, Users).

Comments