charieswei
/
vibe-coding-cn
mirror of https://github.com/tukuaiai/vibe-coding-cn.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
vibe-coding-cn/i18n/en/documents/Templates and Resources/General Project Architectur...

19 KiB
Raw Blame History

General Project Architecture Template

1️⃣ Standard Structure for Python Web/API Projects

project_name/
├── README.md                 # Project README
├── LICENSE                   # Open-source license
├── requirements.txt          # Dependency management (pip)
├── pyproject.toml           # Modern Python project configuration (recommended)
├── setup.py                 # Package installation script (if packaged as a library)
├── .gitignore              # Git ignore file
├── .env                    # Environment variables (not committed to Git)
├── .env.example            # Example environment variables
├── CLAUDE.md              # Claude persistent context
├── AGENTS.md              # Codex persistent context
├── Sublime-Text.txt                   # For requirements and notes, for self-reference, and CLI session recovery commands ^_^
│
├── docs/                   # Documentation directory
│   ├── api.md             # API documentation
│   ├── development.md     # Development guide
│   └── architecture.md    # Architecture description
│
├── scripts/               # Script tools
│   ├── deploy.sh          # Deployment script
│   ├── backup.sh          # Backup script
│   └── init_db.sh         # Database initialization
│
├── tests/                 # Test code
│   ├── __init__.py
│   ├── conftest.py        # pytest configuration
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── test_config.py     # Configuration tests
│
├── src/                   # Source code (recommended)
│   ├── __init__.py
│   ├── main.py           # Program entry point
│   ├── app.py            # Flask/FastAPI application
│   ├── config.py         # Configuration management
│   │
│   ├── core/             # Core business logic
│   │   ├── __init__.py
│   │   ├── models/       # Data models
│   │   ├── services/     # Business services
│   │   └── utils/        # Utility functions
│   │
│   ├── api/              # API interface layer
│   │   ├── __init__.py
│   │   ├── v1/           # Version 1
│   │   └── dependencies.py
│   │
│   ├── data/             # Data processing
│   │   ├── __init__.py
│   │   ├── repository/   # Data access layer
│   │   └── migrations/   # Database migrations
│   │
│   └── external/         # External services
│       ├── __init__.py
│       ├── clients/      # API clients
│       └── integrations/ # Integration services
│
├── logs/                  # Log directory (not committed to Git)
│   ├── app.log
│   └── error.log
│
└── data/                  # Data directory (not committed to Git)
    ├── raw/               # Raw data
    ├── processed/         # Processed data
    └── cache/             # Cache

Use Cases: Flask/FastAPI Web applications, RESTful API services, Web backends

2️⃣ Standard Structure for Data Science/Quant Projects

project_name/
├── README.md
├── LICENSE
├── requirements.txt
├── .gitignore
├── .env
├── .env.example
├── CLAUDE.md              # Claude persistent context
├── AGENTS.md              # Codex persistent context
├── Sublime-Text.txt                   # For requirements and notes, for self-reference, and CLI session recovery commands ^_^
│
├── docs/                   # Documentation directory
│   ├── notebooks/         # Jupyter documentation
│   └── reports/           # Analysis reports
│
├── notebooks/             # Jupyter Notebook
│   ├── 01_data_exploration.ipynb
│   ├── 02_feature_engineering.ipynb
│   └── 03_model_training.ipynb
│
├── scripts/               # Script tools
│   ├── train_model.py     # Training script
│   ├── backtest.py        # Backtest script
│   ├── collect_data.py    # Data collection
│   └── deploy_model.py    # Model deployment
│
├── tests/                 # Tests
│   ├── test_data/
│   └── test_models/
│
├── configs/               # Configuration files
│   ├── model.yaml
│   ├── database.yaml
│   └── trading.yaml
│
├── src/                   # Source code
│   ├── __init__.py
│   │
│   ├── data/              # Data processing module
│   │   ├── __init__.py
│   │   ├── collectors/    # Data collectors
│   │   ├── processors/    # Data cleaning
│   │   ├── features/      # Feature engineering
│   │   └── loaders.py     # Data loaders
│   │
│   ├── models/            # Model module
│   │   ├── __init__.py
│   │   ├── strategies/    # Trading strategies
│   │   ├── backtest/      # Backtest engine
│   │   └── risk/          # Risk management
│   │
│   ├── utils/             # Utility module
│   │   ├── __init__.py
│   │   ├── logging.py     # Log configuration
│   │   ├── database.py    # Database tools
│   │   └── api_client.py  # API client
│   │
│   └── core/              # Core module
│       ├── __init__.py
│       ├── config.py      # Configuration management
│       ├── signals.py     # Signal generation
│       └── portfolio.py   # Portfolio
│
├── data/                  # Data directory (Git ignored)
│   ├── raw/               # Raw data
│   ├── processed/         # Processed data
│   ├── external/          # External data
│   └── cache/             # Cache
│
├── models/                # Model files (Git ignored)
│   ├── checkpoints/       # Checkpoints
│   └── exports/           # Exported models
│
└── logs/                  # Logs (Git ignored)
    ├── trading.log
    └── errors.log

Use Cases: Quantitative trading, machine learning, data analysis, AI research

3️⃣ Monorepo (Multi-Project Repository) Standard Structure

project_name-monorepo/
├── README.md
├── LICENSE
├── .gitignore
├── .gitmodules           # Git submodules
├── docker-compose.yml    # Docker orchestration
├── CLAUDE.md              # Claude persistent context
├── AGENTS.md              # Codex persistent context
├── Sublime-Text.txt                   # This is a file, for requirements and notes, for self-reference, and CLI session recovery commands ^_^
│
├── docs/                 # Global documentation
│   ├── architecture.md
│   └── deployment.md
│
├── scripts/              # Global scripts
│   ├── build_all.sh
│   ├── test_all.sh
│   └── deploy.sh
│
├── backups/                 # Backup files
│   ├── archive/             # Old backup files
│   └── gz/                  # Gzip backup files
│
├── services/             # Microservice directory
│   │
│   ├── user-service/     # User service
│   │   ├── Dockerfile
│   │   ├── requirements.txt
│   │   ├── src/
│   │   └── tests/
│   │
│   ├── trading-service/  # Trading service
│   │   ├── Dockerfile
│   │   ├── requirements.txt
│   │   ├── src/
│   │   └── tests/
│   ...
│   └── data-service/     # Data service
│       ├── Dockerfile
│       ├── requirements.txt
│       ├── src/
│       └── tests/
│
├── libs/                 # Shared libraries
│   ├── common/           # Common modules
│   │   ├── utils/
│   │   └── models/
│   ├── external/         # Third-party libraries (immutable, call only)
│   └── database/         # Database access library
│
├── infrastructure/       # Infrastructure
│   ├── terraform/        # Cloud resource definition
│   ├── kubernetes/       # K8s configuration
│   └── nginx/            # Reverse proxy configuration
│
└── monitoring/           # Monitoring system
    ├── prometheus/       # Metrics collection
    ├── grafana/          # Visualization
    └── alertmanager/     # Alerts

Use Cases: Microservice architecture, large projects, team collaboration

4️⃣ Standard Structure for Full-Stack Web Applications

project_name/
├── README.md
├── LICENSE
├── .gitignore
├── docker-compose.yml    # Frontend and backend orchestration
├── CLAUDE.md              # Claude persistent context
├── AGENTS.md              # Codex persistent context
├── Sublime-Text.txt                   # This is a file, for requirements and notes, for self-reference, and CLI session recovery commands ^_^
│
├── frontend/             # Frontend directory
│   ├── public/           # Static assets
│   ├── src/              # Source code
│   │   ├── components/   # React/Vue components
│   │   ├── pages/        # Pages
│   │   ├── store/        # State management
│   │   └── utils/        # Utilities
│   ├── package.json      # NPM dependencies
│   └── vite.config.js    # Build configuration
│
└── backend/              # Backend directory
    ├── requirements.txt
    ├── Dockerfile
    ├── src/
    │   ├── api/          # API interfaces
    │   ├── core/         # Business logic
│   │   └── models/       # Data models
    └── tests/

Use Cases: Full-stack applications, SPA single-page applications, frontend/backend separated projects

📌 Core Design Principles

1. Separation of Concerns

API → Service → Data Access → Database
Clear at a glance, clear hierarchy

2. Testability

Each module is independently testable
Dependencies can be mocked

3. Configurability

Configuration separated from code
Environment variables > Configuration files > Default values

4. Maintainability

Self-documenting code
Reasonable file naming
Clear directory structure

5. Version Control Friendly (Git-Friendly)

data/, logs/, models/ added to .gitignore
Only commit source code and configuration examples

🎯 Best Practice Recommendations

  1. Use src/ directory: Place source code in a dedicated src directory to avoid top-level clutter.
  2. Relative imports: Consistently use from src.module import thing for imports.
  3. Test coverage: Ensure core business logic has unit and integration tests.
  4. Document first: Write README.md for important modules.
  5. Environment isolation: Use virtualenv or conda to create isolated environments.
  6. Explicit dependencies: All dependencies written to requirements.txt and versions locked.
  7. Configuration management: Use a combination of environment variables + configuration files.
  8. Logging levels: DEBUG, INFO, WARNING, ERROR, FATAL.
  9. Error handling: Do not swallow exceptions; have a complete error chain.
  10. Code style: Use black for formatting, flake8 for checking.

🔥 .gitignore Recommended Template

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
*.egg-info/
dist/
build/

# Environment
.env
.venv/
env/
venv/
ENV/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# Data
data/
*.csv
*.json
*.db
*.sqlite
*.duckdb

# Logs
logs/
*.log

# Models
models/
*.h5
*.pkl

# Temporary files
tmp/
temp/
*.tmp
.DS_Store

📚 Technology Selection Reference

Scenario Recommended Tech Stack
Web API FastAPI + Pydantic + SQLAlchemy
Data Processing Pandas + NumPy + Polars
Machine Learning Scikit-learn + XGBoost + LightGBM
Deep Learning PyTorch + TensorFlow
Databases PostgreSQL + Redis
Message Queue RabbitMQ / Kafka
Task Queue Celery
Monitoring Prometheus + Grafana
Deployment Docker + Docker Compose
CI/CD GitHub Actions / GitLab CI

📝 File Template Examples

requirements.txt

# Core dependencies
fastapi==0.104.1
uvicorn[standard]==0.24.0
pydantic==2.5.0

# Database
sqlalchemy==2.0.23
alembic==1.12.1
psycopg2-binary==2.9.9

# Testing
pytest==7.4.3
pytest-cov==4.1.0
pytest-asyncio==0.21.1

# Utilities
python-dotenv==1.0.0
loguru==0.7.2

# Development (optional)
black==23.11.0
flake8==6.1.0
mypy==1.7.1

pyproject.toml (Recommended for modern Python projects)

[project]
name = "Project Name"
version = "0.1.0"
description = "Project Description"
authors = [{name = "Author", email = "email@example.com"}]
dependencies = [
    "fastapi>=0.104.0",
    "uvicorn[standard]>=0.24.0",
    "sqlalchemy>=2.0.0",
]

[project.optional-dependencies]
dev = ["pytest", "black", "flake8", "mypy"]

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

✅ New Project Checklist

When starting a new project, ensure the following are completed:

  • Create README.md, including project overview and usage instructions.
  • Create LICENSE file, clarifying the open-source license.
  • Set up Python virtual environment (venv/conda).
  • Create requirements.txt and lock dependency versions.
  • Create .gitignore, excluding sensitive and unnecessary files.
  • Create .env.example, explaining required environment variables.
  • Design directory structure, adhering to the principle of separation of concerns.
  • Create basic configuration files.
  • Set up code formatter (black).
  • Set up code checker (flake8/ruff).
  • Write the first test case.
  • Set up Git repository and commit initial code.
  • Create CHANGELOG.md, recording version changes.

In programming / software development, Project Architecture / Software Architecture refers to:

The design solution for how a project is broken down, organized, communicated, and evolved at the "overall level" —it determines how code is layered, how modules are divided, how data flows, and how the system expands and is maintained.

One-Sentence Understanding

Project Architecture = Deciding "where the code goes, how modules connect, and how responsibilities are divided" before writing any specific business code.

I. What Problems Does Project Architecture Primarily Solve?

Project architecture is not about "coding skills," but about solving these higher-level problems:

  • 📦 How to organize code to avoid chaos?
  • 🔁 How do modules communicate?
  • 🧱 Which parts can be modified independently without affecting the whole?
  • 🚀 How will the project be extended in the future?
  • 🧪 How to facilitate testing, debugging, and deployment?
  • 👥 How to collaborate without stepping on each other's code?

II. What Does Project Architecture Generally Include?

1️⃣ Directory Structure (Most Intuitive)

project/
├── src/
│   ├── main/
│   ├── services/
│   ├── models/
│   ├── utils/
│   └── config/
├── tests/
├── docs/
└── README.md

👉 Determines "where different types of code are placed".

2️⃣ Layered Design (Core)

The most common is Layered Architecture:

Presentation Layer (UI / API)
   ↓
Business Logic Layer (Service)
   ↓
Data Access Layer (DAO / Repository)
   ↓
Database / External Systems

Rules:

  • Upper layers can call lower layers.
  • Lower layers cannot depend on upper layers.

3️⃣ Module Partitioning (Responsibility Boundaries)

For example, a trading system:

- market_data   # Market data
- strategy      # Strategy
- risk          # Risk control
- order         # Order placement
- account       # Account

👉 Each module:

  • Does only one type of thing.
  • Aims for low coupling, high cohesion.

4️⃣ Data and Control Flow

  • Where does the data come from?
  • Who is responsible for processing?
  • Who is responsible for storage?
  • Who is responsible for external output?

For example:

WebSocket → Data Cleaning → Indicator Calculation → AI Scoring → SQLite → API → Frontend

5️⃣ Technology Selection (Part of Architecture)

  • Programming languages (Python / Java / Go)
  • Frameworks (FastAPI / Spring / Django)
  • Communication methods (HTTP / WebSocket / MQ)
  • Storage (SQLite / Redis / PostgreSQL)
  • Deployment (Local / Docker / Cloud)

III. Common Project Architecture Types (Essential for Beginners)

1️⃣ Monolithic Architecture

One project, one process

Suitable for:

  • Personal projects
  • Prototypes
  • Small systems

Advantages:

  • Simple
  • Easy to debug

Disadvantages:

  • Difficult to scale later

2️⃣ Layered Architecture (Most Common)

Controller → Service → Repository

Suitable for:

  • Web backends
  • Business systems

3️⃣ Modular Architecture

core + plugins

Suitable for:

  • Pluggable systems
  • Strategy / indicator systems

👉 Very suitable for quant, AI analysis you are doing.

4️⃣ Microservice Architecture (Advanced)

Each service is an independent process + API communication

Suitable for:

  • Large teams
  • High concurrency
  • Long-term evolution

❌ Not recommended for beginners to start with.

IV. Understanding with a "Real Example" (Close to what you are doing now)

Suppose you are building a Binance Futures AI Analysis System:

backend/
├── data/
│   └── binance_ws.py        # Market data subscription
├── indicators/
│   └── vpvr.py
├── strategy/
│   └── signal_score.py
├── storage/
│   └── sqlite_writer.py
├── api/
│   └── http_server.py
└── main.py

This is project architecture design:

  • Each folder is responsible for one thing.
  • Replaceable, testable.
  • Later, if you want to connect a Telegram Bot / Web frontend, you don't need to rewrite the core.

V. Common Misconceptions for Beginners ⚠️

❌ Starting with microservices ❌ All code in one file ❌ Architecture pursuing "seniority" rather than "maintainability" ❌ Starting to write code without clearly thinking about data flow

VI. Suggested Learning Path (Very Important)

If you are learning CS now, this order is highly recommended:

  1. First write runnable projects (imperfect).

  2. Code becomes messy → then learn architecture.

  3. Learn:

    • Module decomposition
    • Layering
    • Dependency direction

  4. Then learn:

    • Design patterns
    • Microservices / message queues

Version: 1.0 Update Date: 2025-11-24 Maintained by: CLAUDE, CODEX, KIMI