Skip to content

README.md

Latest commit

 

History

History
169 lines (126 loc) · 6.48 KB

README.md

File metadata and controls

169 lines (126 loc) · 6.48 KB
Raw

DevMind

English | 中文

AI-powered acceleration platform for internal enterprise use, enabling AI-driven R&D project management, financial data analysis, and other intelligent workflows.

Architecture Overview

devmind/
├── backend/               # Django REST API
│   ├── core/              # Project config (settings/, urls.py, celery.py, periodic_registry.py)
│   ├── accounts/          # Auth, Profile, Role, Permission
│   ├── cloud_billing/     # Cloud billing (AWS / Azure / Alibaba / Huawei / Tencent)
│   ├── data_collector/    # Raw data collection from JIRA, Feishu, etc.
│   ├── ai_pricehub/       # AI model price comparison
│   ├── app_config/        # Global config (Feature Flags)
│   └── agentcore/         # Git submodules
│       ├── agentcore-metering/   # LLM usage tracking  → /api/v1/admin/
│       ├── agentcore-task/       # Unified task mgmt  → /api/v1/tasks/
│       └── agentcore-notifier/   # Feishu notifier    → /api/v1/admin/notifications/
└── frontend/              # Vue 3 (Vite + Pinia + Tailwind + vue-i18n)

Key architectural notes:

  • All data is stored in UTC; frontend converts to user's local timezone
  • Each Django app is self-contained (owns its own models, views, serializers, services, migrations, tests)
  • Periodic tasks are declared in periodic_tasks.register_periodic_tasks() and written to django_celery_beat; existing records are never overwritten

Quick Start

1. Fetch submodules (required after cloning)

git submodule update --init --recursive

2. Configure and start (Docker dev)

cp env.sample .env.dev
# Edit .env.dev — configure database, AI services, etc.
docker-compose -f docker-compose.dev.yml up -d

3. Access services

Service URL
Web UI http://localhost:8000
API Docs http://localhost:8000/swagger/
Admin Panel http://localhost:8000/admin/
Celery Monitor http://localhost:5555

4. Common Commands

# Backend
pytest                                    # Run all tests
pytest path/to/test.py                    # Single test file
black --check backend/                    # Check formatting
isort --check backend/                   # Check import order

# Django management
python backend/manage.py migrate
python backend/manage.py register_periodic_tasks   # Register periodic tasks
python backend/manage.py createsuperuser

# Frontend
cd frontend && npm install
npm run dev          # Dev server
npm run build        # Production build
npm run lint
npm run test:e2e     # Playwright E2E

Agentcore Submodules in Detail

Common modules (LLM tracking, task management, notifier) are maintained as separate repositories and included as git submodules.

Installation by Environment

Environment Approach
Production (Docker) pyproject.toml dependencies point to GitHub; installed automatically during image build
Dev (Docker) DEV_MODE=1 image additionally runs pip install -e . to overlay local agentcore
Local / non-Docker After cloning, manually pip install -e "$d" per submodule (see below)

Local Editable Install

for d in backend/agentcore/*/; do
  [ -f "${d}pyproject.toml" ] && pip install -e "$d"
done

Submodule Mapping

Submodule Django app (INSTALLED_APPS) URL prefix
agentcore-metering agentcore_metering.adapters.django /api/v1/admin/
agentcore-task agentcore_task.adapters.django /api/v1/tasks/
agentcore-notifier agentcore_notifier.adapters.django /api/v1/admin/notifications/

Celery: Task Discovery and Periodic Task Registration

Task Discovery

core/celery.py calls app.autodiscover_tasks() which automatically loads tasks.py from every app in INSTALLED_APPS. Any Django app in INSTALLED_APPS that provides a tasks.py is discovered automatically — no extra configuration needed.

Periodic Task Registration

Periodic (cron-like) tasks are not auto-discovered by Celery alone. They must be written to django_celery_beat via python manage.py register_periodic_tasks:

  1. Iterates over every app in INSTALLED_APPS looking for a periodic_tasks module
  2. If the module defines register_periodic_tasks(), it is called
  3. Each app declares cron entries using core.periodic_registry
  4. The registry only creates missing rows — existing django_celery_beat records are left untouched

Entrypoint.sh Execution Order

Container Behavior
backend-init wait_for_db → migrate
backend-runtime-init wait_for_db → bootstrap runtime catalogs → register_periodic_tasks → optional collectstatic
gunicorn / development wait_for_db → start service
celery wait_for_db → start worker (autodiscover_tasks loads tasks)
celery-beat waits for backend-runtime-init → start beat (DatabaseScheduler reads schedule from DB)

In a typical multi-container setup, API startup only waits for migrations. Runtime maintenance runs in a separate one-shot container, and celery-beat starts after periodic tasks have been registered.

Design Principles

For decoupling, each application (app) must manage its own resources—including database, APIs, and configuration. See docs/DESIGN_PRINCIPLES.md.
设计原则（中文）：docs/DESIGN_PRINCIPLES.zh-CN.md.

Production Deployment

cp env.sample .env
# Edit .env: SECRET_KEY, DJANGO_DEBUG=false, ALLOWED_HOSTS, database, AI services, etc.
APP_VERSION=1.2.3 docker-compose -f docker-compose.yml up -d

Default ports: HTTP 10080, HTTPS 10443 (configurable via NGINX_HTTP_PORT / NGINX_HTTPS_PORT)

The production image version is controlled by APP_VERSION. When deploying from a Git tag, GitHub Actions strips the leading v (for example, v1.2.3 becomes APP_VERSION=1.2.3) and runs docker-compose pull plus docker-compose up -d. For manual deployments, set APP_VERSION explicitly or Compose will fail with APP_VERSION is required.

Frontend

  • Vue 3 + Composition API + <script setup>
  • Vite + Pinia + Vue Router + vue-i18n + Tailwind CSS
  • E2E: Playwright
cd frontend
npm install
npm run dev          # http://localhost:5173
npm run build        # Docker: use root `Dockerfile --target frontend`

Environment variables: VITE_API_BASE_URL, VITE_APP_TITLE, VITE_APP_VERSION, VITE_API_TIMEOUT