# AI Context & Project Overview

## Project Identity
**Project Name**: Telegram Earn
**Description**: A Telegram Mini App for earning rewards, featuring user wallets, investment tiers, referral systems, and crypto transactions.

## Workspace Structure
The project is split into two main repositories/directories within the workspace:

1.  **Backend** (`telegram-earn/backend`)
    -   **Framework**: Django 5.2 (Python 3.10+) with Django REST Framework.
    -   **Database**: MySQL 8.0+.
    -   **Virtual Environment**: Python virtual environment located at `telegram-earn/backend/venv`.
    -   **Environment**: `.env` file located at `telegram-earn/backend/.env`.
    -   **Entry Point**: `manage.py` located at `telegram-earn/backend/manage.py`.
    -   **Core Apps**: `users`, `investments`, `referrals`, `transactions`, `payments`.

2.  **Frontend** (`telegram-earn-fe`)
    -   **Framework**: Vite + React (TypeScript).
    -   **Path**: `/Users/neowong/Sites/mscumec/telegram-earn-fe` (Sibling directory to `telegram-earn`).
    -   **Key Libraries**: `zustand` (State), `react-query` (Data Fetching), `react-router-dom` (Routing), `@twa-dev/sdk` (Telegram SDK).
    -   **Config**: `vite.config.ts`, `tsconfig.json`.

## Key Documentation Pointers
For detailed architectural rules, always refer to these existing documents first:
-   **Requirements**: [requirements-analysis.md](file:///Users/neowong/Sites/mscumec/telegram-earn/docs/requirements-analysis.md) (Full project specs).
-   **Backend Architecture**: [backend-architecture.md](file:///Users/neowong/Sites/mscumec/telegram-earn/docs/backend-architecture.md) (Database schema, Models, Authentication).
-   **Frontend Architecture**: [frontend-architecture.md](file:///Users/neowong/Sites/mscumec/telegram-earn/docs/frontend-architecture.md).
-   **Business Rules**: [mlm-business-rules.md](file:///Users/neowong/Sites/mscumec/telegram-earn/docs/mlm-business-rules.md).

## Operational Context
-   **Authentication**: Uses Telegram `initData` validation to issue JWT tokens.
-   **Financials**: All monetary values use `Decimal` with 8 decimal places.
-   **Transactions**: Hybrid model using structured fields for indexing and JSON `data` field for metadata.

## Important Commands
-   **Setup Backend Environment** (before running Django apps):
    1.  Activate virtual environment: `source telegram-earn/backend/venv/bin/activate`
    2.  Export environment variables: `cd telegram-earn/backend && set -a; source .env; set +a`
-   **Run Backend**: `python manage.py runserver` (from `backend/` dir, after activating venv and exporting .env).
-   **Run Frontend**: `npm run dev` (from `telegram-earn-fe/` dir).
-   **Make Migrations**: `python manage.py makemigrations` / `python manage.py migrate`.