🎉 Thank You for Your Interest in Argo!

July 17, 2025 · View on GitHub

Argo is a modular AI Agent system that integrates components like LLM, multi-agent support, MCP tool protocol, and frontend-backend collaboration. We welcome all forms of contributions, including but not limited to:

Bug fixes
New feature development
Performance optimization
Documentation improvements
Cross-platform support
Deployment enhancements

📁 Project Structure Overview

Backend

Argo's backend is written in Python using the Tornado framework and uses SQLAlchemy as the ORM.

backend/
├── alembic/        # Database migration scripts (Alembic)
├── configs/        # Configuration loading and initialization
├── core/           # Core modules for Agent / LLM / MCP
├── dist/           # Frontend build artifacts (output from frontend, used for backend static serving, can be ignored)
├── docker/         # Docker configs
├── events/         # Async event definitions and handlers
├── handlers/       # HTTP controllers (Tornado Handlers)
├── models/         # ORM data models (SQLAlchemy, etc.)
├── resources/      # Static resources
├── schemas/        # Request schema definitions and validation (Marshmallow Schema)
├── services/       # Core business logic (Service layer)
├── templates/      # swagger.json, HTML templates, etc.
├── tests/          # Unit tests
├── utils/          # Utility functions
└── main.py         # Application entry point

Frontend

The frontend is built with Vite + React based on TypeScript.

frontend/
├── public/               # Public assets
├── src/                  # Source code
│   ├── assets/           # Static assets (images, SVGs, audio, etc.)
│   ├── components/       # Reusable UI components (buttons, inputs, modals, etc.)
│   ├── hooks/            # Custom React hooks (e.g. useFetch, useTheme)
│   ├── layout/           # Layout components (Header, Sidebar, Footer)
│   ├── lib/              # Shared libraries/clients (e.g. request library, 3rd-party wrappers)
│   ├── pages/            # Page components (each page is a module)
│   ├── routes/           # Route definitions (e.g. react-router-dom Route setup)
│   ├── types/            # Global TypeScript interfaces/types
│   ├── utils/            # Utility functions (date, formatting, validation, etc.)
│   ├── App.tsx           # Root React component
│   ├── App.css           # Styles for App component
│   ├── constants.tsx     # App-wide constants
│   ├── index.css         # Global styles
│   ├── main.tsx          # App entry point, ReactDOM.createRoot mount point
│   ├── tailwind.css      # Tailwind CSS entry configuration
│   └── vite-env.d.ts     # Vite environment variable type definitions
└── index.html            # HTML entry template for Vite to inject build artifacts

📌 Before You Start

Please review:

Existing Issues
For new features, please start a discussion or create an issue to align direction before starting development
For bug fixes, minor features, or documentation updates, you may open a PR directly

🚀 Quick Start (Developers)

Refer to docs/DEV_GUIDE_CN.md for setting up the local development environment.

✅ Covers .env setup, frontend/backend build, dependency installation, service startup, and more.

🧑‍💻 Contribution Workflow

1. Fork & Clone

git clone https://github.com/<your-name>/argo.git
cd argo
git remote add upstream https://github.com/xark-argo/argo.git

2. Create a Feature Branch

Suggested naming format:

git checkout -b feat/agent-mem-optimization

Recommended branch types:

Type	Example
Feature	`feat/model-selector-ui`
Fix	`fix/invalid-token-error`
Docs	`docs/add-contributing-guide`
Build	`build/pyinstaller-hook`
Refactor	`refactor/database-layer`

📦 Commit Message Convention (Use Conventional Commits)

Example format:

feat(agent): support multi-agent state isolation

fix(api): fix incorrect API response

docs(readme): add local dev setup instructions

Common types:

feat: new feature
fix: bug fix
docs: documentation only
style: formatting (no code logic changes)
refactor: code refactoring
test: add or update tests
build: build-related changes (Docker, CI, PyInstaller, etc.)
chore: miscellaneous changes (e.g., dependency upgrades)

✅ Pre-commit Checklist

Before submitting a PR, please ensure you’ve run:

make format         # Code formatting
make lint           # Mypy + Ruff + basic test checks
make build-web      # If frontend code is changed

📄 PR Submission Process

Push your feature branch:
```
git push origin feat/your-feature
```
Create a Pull Request, and ensure it includes:
- ✅ Clear title and description of changes
- ✅ Whether it introduces breaking changes
- ✅ Whether it affects UI or model compatibility
- ✅ If it’s UI-related, provide screenshots or demo
Wait for Maintainers to review and discuss ✅