Finansia Portal

# Manual ICO Web

ICO Web — Project Migration Document

> **Note:** This project was originally scaffolded using [Vite](https://vitejs.dev/) (`create-vite` with the React/TypeScript template).

---

## 1. Stack & Prerequisites

### Tech Stack

| Category             | Technology           | Version |

| -------------------- | -------------------- | ------- |

| **Language**         | TypeScript           | ^5.6.3  |

| **Framework**        | React                | ^18.3.1 |

| **Build Tool**       | Vite                 | ^6.3.5  |

| **Styling**          | Tailwind CSS         | ^3.4.11 |

| **State Management** | Redux Toolkit        | ^2.2.7  |

| **Routing**          | React Router DOM     | ^6.26.2 |

| **HTTP Client**      | Axios                | ^1.7.7  |

| **Form**             | React Hook Form      | ^7.53.0 |

| **Form Validation**  | Zod                  | ^3.23.8 |

| **i18n**             | i18next              | ^25.7.4 |

| **Testing**          | Jest                 | ^29.7.0 |

| **Linting**          | ESLint               | ^8.56.0 |

| **Container**        | Docker (multi-stage) | —       |

| **Web Server**       | Nginx Alpine         | —       |

### Prerequisites to Install

| Tool        | Version       |

| ----------- | ------------- |

| **Node.js** | LTS (v20/v22) |

| **Yarn**    | Berry (v2+)   |

| **Docker**  | 20+           |

| **Git**     | 2.x           |

### Verify Installations

```bash

node -v       # v20.x or v22.x

yarn -v       # 4.x (Berry)

docker -v     # Docker version 20+

git --version # git version 2.x

```

---

## 3. Package Manager

This project uses **Yarn Berry (v2+)** with classic `node_modules` linker.

### Configuration

File: `.yarnrc.yml`

```yaml

nodeLinker: node-modules

```

### Common Commands

```bash

# Install all dependencies

yarn install

# Add a new dependency

yarn add <package-name>

# Add a dev dependency

yarn add -D <package-name>

# Remove a dependency

yarn remove <package-name>

```

### Scripts (from package.json)

```bash

yarn dev                    # Start Vite dev server (http://localhost:5173)

yarn build                  # TypeScript check + production build → /dist

yarn test                   # Run Jest tests

```

---

## 4. Project Architecture

### 4.1 Routing (React Router DOM v6)

**Entry:** `src/app/AppRoutes.tsx`

All routes are defined in a single file using `<Routes>` and `<Route>`. The app wraps routes in a `<HelmetLayout>` for SEO.

**Route groups:**

| Group                 | Path Pattern         | Pages                                                                                      |

| --------------------- | -------------------- | ------------------------------------------------------------------------------------------ |

| **Landing**           | `/`                  | Landing page, investment campaign                                                          |

| **Auth**              | `/login`, `/reset-*` | Login, reset password, Google Authenticator                                                |

| **Sign Up (Thai)**    | `/signup/*`          | Type select → corporate/individual → basicinfo → suite test → OTP → ID card → verification |

| **Sign Up (Foreign)** | `/foreign/*`         | Fullname → CRS → basicinfo → suite test → doc upload → OTP                                 |

| **Re-KYC**            | `/rekyc/*`           | Re-KYC flow, FATCA, suite test, ID card                                                    |

| **Portfolio**         | `/portfolio`         | Portfolio management                                                                       |

| **Marketplace**       | `/marketplace`       | Marketplace + TOTP confirmation                                                            |

| **Order & Trade**     | `/order-trade`       | Order trade + high net worth verification                                                  |

| **Subscription**      | `/subscription`      | Subscription page                                                                          |

| **Asset Details**     | `/asset-details/*`   | ICO details, white paper, filing                                                           |

| **Fraction Exchange** | `/fraction-exchange` | Fraction exchange                                                                          |

| **Static Pages**      | `/contact-us`, etc.  | Contact, policy, complaint, about us, terms                                                |

| **Error**             | `*`                  | 404 page                                                                                   |

---

### 4.2 State Management (Redux Toolkit)

**Store:** `src/redux/store.tsx`

```

Redux Store

└── redux/

   ├── store

   └── slice/

```

---

### 4.3 API Layer (Axios)

**File:** `src/api/axios.tsx`

The project creates multiple Axios instances, all with `baseURL: window.origin` (same-origin proxy):

| Instance          | Purpose                            | Auth         |

| ----------------- | ---------------------------------- | ------------ |

| `default export`  | Basic API calls                    | Cookies only |

| `axiosCheckToken` | Authenticated calls with refresh   | Auto-refresh |

| `axiosMultipart`  | File uploads (multipart/form-data) | Cookies      |

| `axiosNoAuth`     | Public API calls                   | None         |

**Token refresh flow:**

1. Request interceptor checks if refresh token is expired → redirect to login if so

2. If access token is expired, calls `POST /api/v1/authen/customers/refresh`

3. Queues failed requests in `failedQueue` while refresh is in-flight

4. On success, retries all queued requests with new token

5. In dev mode (`isDev()`), token checks are skipped entirely

**Helper:** `getCustomAxios()` returns `axiosCheckToken` if access token exists, otherwise `axiosNoAuth`.

---

### 4.4 Form Handling

| Library                 | Purpose                            |

| ----------------------- | ---------------------------------- |

| **React Hook Form**     | Form state, validation, submission |

| **Zod**                 | Schema-based validation            |

| **@hookform/resolvers** | Connects Zod schemas to RHF        |

---

### 4.5 Internationalization (i18n)

**File:** `src/i18n/config.ts`

| Setting               | Value                                                          |

| --------------------- | -------------------------------------------------------------- |

| **Library**           | i18next + react-i18next                                        |

| **Languages**         | `en` (English), `th` (Thai)                                    |

| **Fallback**          | `en`                                                           |

| **Detection**         | localStorage → navigator → htmlTag                             |

| **Storage key**       | `i18nextLng` (localStorage)                                    |

| **Translation files** | `public/locales/{lng}/{ns}.json`                               |

| **Namespaces**        | `common`, `footer`, `navbar`, `landing`, `signup`, `portfolio` |

| **Default ns**        | `common`                                                       |

---

### 4.6 Styling

| Tool               | Config File            | Notes                                       |

| ------------------ | ---------------------- | ------------------------------------------- |

| **Tailwind CSS**   | `tailwind.config.js`   | Custom font: Anuphan, custom colors/screens |

| **CSS**            | `src/index.css`        | Global styles                               |

| **PostCSS**        | `postcss.config.js`    | Tailwind + Autoprefixer plugins             |

| **tailwind-merge** | via `src/lib/utils.ts` | `cn()` helper for conditional classes       |

---

### 4.7 Key Libraries

| Library                 | Purpose                                  |

| ----------------------- | ---------------------------------------- |

| `crypto-js`             | Encryption/decryption (with pepper keys) |

| `jwt-decode`            | Decode JWT tokens (expiry check)         |

| `js-cookie`             | Cookie management (access/refresh token) |

| `dayjs`                 | Date/time formatting (with UTC/timezone) |

| `lodash`                | Utility functions                        |

| `react-toastify`        | Toast notifications                      |

| `react-helmet-async`    | SEO meta tags                            |

| `apexcharts`            | Interactive charts                       |

| `chart.js`              | Canvas-based charts                      |

| `echarts-for-react`     | ECharts wrapper                          |

| `@tanstack/react-table` | Headless table                           |

| `swiper`                | Carousel/slider                          |

| `leaflet`               | Map component                            |

| `filepond`              | File upload widget                       |

| `react-webcam`          | Webcam capture (ID card/liveness)        |

---

## 5. Environment Variables

### 5.1 Variable List

All variables use the `VITE_` prefix (required by Vite to expose to client-side code):

| Variable              | Required | Description                                  |

| --------------------- | -------- | -------------------------------------------- |

| `VITE_BASE_URL`       | Yes      | Backend API base URL                         |

| `VITE_REKOGNITOR_URL` | Yes      | AWS Rekognition / face liveness service URL  |

| `VITE_STATIC_URL`     | Yes      | Static file server URL (images, documents)   |

| `VITE_BUCKET_URL`     | Yes      | S3 bucket URL for uploads/downloads          |

| `VITE_PEPER`          | Yes      | Encryption pepper (used with crypto-js)      |

| `VITE_BACK_REGISTER`  | Yes      | Backend registration endpoint pepper         |

| `VITE_CID_PEPER`      | Yes      | CID (citizen ID) encryption pepper           |

| `VITE_ENVIRONMENT`    | Yes      | Environment name: `dev`, `uat`, `production` |

### 5.2 Environment Variable Injection (CI/CD Pipeline)

**Workflow process:**

1. **Build Phase:** The React app is built using Vite. During this build use config paceholder `VITE_*` (e.g., the string `"VITE_BASE_URL"` instead of a real URL).

2. **Docker Phase:** The `Dockerfile` packages the built static files and an `entrypoint.sh` script into an Nginx image.

3. **Environment Fetching:** Before the application spins up in the target AWS environment, the real environment values are fetched from an `.env` file securely stored in an **AWS S3 bucket**.

4. **Runtime Injection:** When the Docker container starts, it executes `entrypoint.sh`. This shell script uses `sed` to find all the JS bundles that contain the text placeholders and replaces them with the real environment values fetched from S3.

This pattern allows the same Docker image to be promoted across Dev, UAT, and Prod environments just by fetching a different `.env` file from S3

### 5.3 Config File

**File:** `src/config/config.ts`

This file maps environment variables to exported constants used throughout the app:

| Constant              | Source / Env Var      |

| --------------------- | --------------------- |

| `BASE_URL`            | `VITE_BASE_URL`       |

| `BASE_REKOGNITOR_URL` | `VITE_REKOGNITOR_URL` |

| `BASE_STATIC_URL`     | `VITE_STATIC_URL`     |

| `BASE_BUCKET_URL`     | `VITE_BUCKET_URL`     |

| `PEPER`               | `VITE_PEPER`          |

| `PEPER_BACK_REGISTER` | `VITE_BACK_REGISTER`  |

| `PEPER_CID`           | `VITE_CID_PEPER`      |

| `ENVIRONMENT`         | `VITE_ENVIRONMENT`    |