> For the complete documentation index, see [llms.txt](https://optim-finance.gitbook.io/optim-finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://optim-finance.gitbook.io/optim-finance/oada-ui/tutorials/understanding-the-project-structure.md).

# Understanding the Project Structure

This tutorial will help you understand the organization of the OADA UI project, its key components, and how they work together. By the end of this tutorial, you'll be familiar with the project's architecture and be able to navigate the codebase effectively.

### Project Overview

The OADA UI is a React-based frontend application that provides a user interface for interacting with the OADA smart contract platform. The project follows a feature based architecture with clear separation of concerns.

### Directory Structure

```
src/
├── assets/                    # Static assets (images, fonts, etc.)
│
├── components/                # Reusable UI components
│   ├── Alert/                 # Alert component
│   ├── Amount/                # Amount display component
│   ├── Attention/             # Attention/notification component
│   ├── Breadcrumbs/           # Navigation breadcrumbs
│   ├── Button/                # Button components
│   ├── Card/                  # Card components
│   ├── CurrencyLogos.tsx      # Currency logo component
│   ├── DotsLink/              # Dots link component
│   ├── Dropdown/              # Dropdown components
│   ├── Icon/                  # Icon components
│   ├── Info/                  # Info display components
│   ├── InfoPanel/             # Info panel components
│   ├── InputBox/              # Input box components
│   ├── LabelItemContainer/    # Label item container
│   ├── Modal/                 # Modal components
│   ├── Navigator/             # Navigation components
│   ├── PageHeader/            # Page header components
│   ├── providers/             # Context providers
│   ├── SelectInput/           # Select input components
│   ├── Slider/                # Slider components
│   ├── Spinner/               # Loading spinner
│   ├── Tabs/                  # Tab components
│   ├── TextArea/              # Text area components
│   ├── Title/                 # Title components
│   ├── ui/                    # Basic UI components
│   └── WithdrawWallet/        # Wallet withdrawal components
│
├── features/                  # Feature-specific components
│   ├── dAppHub/               # dApp Hub feature
│   │   ├── OADA/              # OADA-specific components
│   │   ├── OptimizLock/       # OptimizLock components
│   │   ├── EpochStakeAuction/ # Epoch Stake Auction components
│   ├── converWallet/          # Wallet conversion feature
│   ├── Topbar/                # Top navigation bar
│   ├── WalletDropdown/        # Wallet dropdown menu
│   ├── Faq/                   # FAQ section
│   └── TopLinks/              # Top navigation links
│
├── mainnet/                   # Mainnet-specific code
├── oada/                      # OADA-specific code
├── preview/                   # Preview-related code
├── scripts/                   # Build and development scripts
├── store/                     # State management
├── types/                     # TypeScript type definitions
├── utils/                     # Utility functions
│
├── App.tsx                    # Main application component
├── App.test.tsx               # App component tests
├── config.local.ts.example    # Example config file
├── index.tsx                  # Application entry point
├── index.scss                 # Global styles
├── JsonRpc.ts                 # JSON-RPC utilities
├── lucid-ext.ts               # Lucid extension
├── main.css                   # Main styles
├── network.ts                 # Network utilities
├── react-app-env.d.ts         # React app type definitions
├── serviceWorker.ts           # Service worker
├── setupTests.ts              # Test setup
├── tx-recipe.ts               # Transaction recipe
├── tx.ts                      # Transaction utilities
├── utils.ts                   # General utilities
└── websocket.tsx              # WebSocket utilities
```

### Key Directories Explained

#### 1. `components/`

This directory contains reusable UI components organized by functionality. Each component is typically a directory containing its implementation, styles, and tests. Key components include:

* `Alert/`: Alert and notification components
* `Button/`: Button components with various styles and states
* `Card/`: Card layout components
* `InputBox/`: Form input components
* `Modal/`: Modal dialog components
* `Tabs/`: Tab navigation components
* `ui/`: Basic UI components used throughout the application

#### 2. `features/`

Contains feature-specific components and logic, organized by feature:

* `dAppHub/`: The main dApp Hub feature with components for:
  * OADA integration
  * OptimizLock functionality
  * Epoch Stake Auction
  * Various UI components like cards, tables, and forms
* `converWallet/`: Wallet conversion functionality
* `Topbar/`: Top navigation bar
* `WalletDropdown/`: Wallet connection dropdown
* `Faq/`: FAQ section
* `TopLinks/`: Top navigation links

#### 3. `store/`

State management using Redux:

* Contains slices for different parts of the application state
* Custom hooks for state access
* Action creators and reducers

#### 4. `utils/`

Utility functions and helpers:

* Network utilities
* Transaction handling
* WebSocket management
* General utility functions

#### 5. `types/`

TypeScript type definitions:

* Component props
* API responses
* State types
* Utility types

### Development Workflow

When creating a new component:

1. Create a new directory in `components/` with the component name
2. Create the following files:

   ```typescript
   // ComponentName/index.tsx
   /**
    * ComponentName Component
    *
    * A description of what this component does and its purpose.
    * Include any important usage notes or examples.
    */

   import React, { FC } from "react";
   import styles from "./index.module.scss";
   import classNames from "classnames";

   /**
    * Component props interface
    *
    * @property prop1 - Description of prop1
    * @property prop2 - Description of prop2
    */
   type Props = {
     prop1: string;
     prop2?: boolean;
     // Add other props as needed
   };

   /**
    * ComponentName Component
    *
    * Detailed description of the component's functionality.
    * Include usage examples if helpful.
    */
   export const ComponentName: FC<Props> = ({ prop1, prop2, ...rest }) => {
     return (
       <div
         className={classNames(
           styles.baseClass,
           { [styles.variantClass]: prop2 },
           rest.className
         )}
       >
         {/* Component content */}
       </div>
     );
   };
   ```

   ```scss
   // ComponentName/index.module.scss
   /**
    * ComponentName Component Styling
    * 
    * SCSS module that defines the styling for the ComponentName component.
    * Include any variations, states, or special cases.
    */

   @import "src/assets/variables";

   .baseClass {
     // Base styles
   }

   .variantClass {
     // Variant styles
   }
   ```

#### 2. Adding New Features

When adding a new feature:

1. Create a new directory in `features/`
2. Organize feature-specific components and logic
3. Create an `index.tsx` file as the feature entry point
4. Add necessary state management in `store/`
5. Add types in `types/`

#### 3. Working with State

When working with state:

1. Create or update slices in `store/slices/`
2. Add actions and reducers
3. Create selectors for state access
4. Use custom hooks for state management

### Best Practices

1. **Component Organization**
   * Keep components small and focused
   * Use composition over inheritance
   * Follow the single responsibility principle
2. **State Management**
   * Use Redux for global state
   * Keep state normalized
   * Use selectors for state access
3. **TypeScript**
   * Use strict type checking
   * Define interfaces for all props
   * Use type guards for runtime type checking
4. **Styling**
   * Use styled-components for component-specific styles
   * Follow the design system guidelines
   * Keep styles modular and reusable

### Next Steps

Now that you understand the project structure, you can proceed to:

1. Basic Configuration and Customization
2. Working with Components

### Additional Resources

* [React Documentation](https://reactjs.org/docs/getting-started.html)
* [Redux Documentation](https://redux.js.org/)
* [TypeScript Documentation](https://www.typescriptlang.org/docs/)