ArchiCore - AI Software Architect

---

📋 Table of Contents

- Overview
- Key Features
- Architecture
- Technology Stack
- Quick Start
- Installation
- Usage
- Web Dashboard
- CLI Tool
- REST API
- Authentication & Security
- Configuration
- Deployment
- API Reference
- Development
- Roadmap
- Contributing
- License

---

📚 Complete Documentation:
- API & CLI Reference - Полная документация всех API endpoints, CLI команд и поддерживаемых языков
- TODO - Список задач и планов развития
- Business Model - Бизнес-модель и ответы на вопросы
- Deployment Guide - Инструкция по развертыванию

---

🎯 Overview

ArchiCore - это интеллектуальная платформа для анализа и управления архитектурой программного обеспечения, построенная на основе AI. Система понимает код на глубоком семантическом уровне, отслеживает все зависимости и помогает принимать обоснованные архитектурные решения.

$3

Проблема: В больших проектах разработчики часто вносят изменения, не понимая полного влияния на систему. Это приводит к багам, техническому долгу и архитектурной деградации.

Решение: ArchiCore анализирует весь код, строит граф зависимостей, использует семантическую память и AI для предсказания влияния изменений, выявления рисков и генерации рекомендаций.

$3

- 👨‍💻 Software Architects - контроль архитектуры, выявление нарушений
- 👩‍💼 Tech Leads - review кода, анализ влияния изменений
- 🏢 Development Teams - снижение багов, улучшение code quality
- 📊 CTO/Engineering Managers - метрики, технический долг, risk assessment

---

✨ Key Features

$3

- AST Parsing - Глубокий синтаксический анализ через Tree-sitter (40+ языков)
- Dependency Graph - Полный граф зависимостей между компонентами, функциями, классами
- Symbol Extraction - Извлечение всех символов: функции, классы, интерфейсы, переменные
- Call Graph Analysis - Граф вызовов для отслеживания потоков данных
- Semantic Memory - Vector database (Qdrant) для семантического понимания кода

$3

- Real-time Impact Detection - Определение затронутых компонентов при изменениях
- Risk Assessment - Автоматическая оценка рисков (Critical, High, Medium, Low)
- Dependency Tracking - Отслеживание прямых и транзитивных зависимостей
- Impact Visualization - Графическое представление влияния изменений
- Smart Recommendations - AI-генерируемые рекомендации по снижению рисков

$3

- Natural Language Queries - Поиск по смыслу: "функции обработки платежей"
- Vector Similarity - Поиск семантически похожих фрагментов кода
- Context-Aware Results - Результаты с учетом контекста и зависимостей
- Multi-language Support - Поиск во всех поддерживаемых языках одновременно

$3

- Architectural Questions - "Как организована аутентификация в системе?"
- Code Review - Автоматический анализ качества и соответствия best practices
- Documentation Generation - Генерация архитектурной документации
- Refactoring Suggestions - Предложения по улучшению архитектуры
- Dead Code Detection - Выявление неиспользуемого кода
- Code Duplication Analysis - Поиск дублирования для рефакторинга

$3

- Multi-Provider OAuth - Google, GitHub authentication
- Email Verification - 6-значные коды, SMTP integration (Zoho)
- Disposable Email Protection - Блокировка 180+ временных email доменов
- JWT Authentication - Secure token-based auth
- Device Flow - Безопасная CLI авторизация через web browser
- API Keys Management - Создание, ротация, отзыв API ключей
- Audit Logs - Полное логирование всех действий пользователей
- Rate Limiting - Защита от abuse и DDoS
- CORS & Helmet - Защита web endpoints
- bcrypt Password Hashing - Industry-standard password security
- AES-256 Encryption - Шифрование чувствительных данных

$3

- Multi-Project Support - Управление несколькими проектами
- Team Collaboration - Совместная работа команд (до 20 разработчиков)
- GitHub Integration - Автоматический анализ PR, webhooks
- Version Control - Отслеживание изменений архитектуры
- Progress Tracking - Метрики качества и технического долга

$3

- Web Dashboard - Интуитивный UI для визуализации и управления
- CLI Tool - Мощный command-line interface для automation
- REST API - Полное API для интеграции с CI/CD и другими системами
- Webhooks - GitHub webhooks для автоматического анализа

$3

- Code Metrics - Cyclomatic complexity, lines of code, maintainability index
- Architecture Metrics - Coupling, cohesion, modularity scores
- Technical Debt Tracking - Идентификация и quantification технического долга
- Trend Analysis - Отслеживание изменений метрик во времени
- Custom Dashboards - Настраиваемые дашборды для команд

$3

- 60+ Language Support - TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, Scala, C#, F#, Swift, Dart, PHP, Ruby, Haskell, Elixir и другие
- IDE Integration - VS Code, JetBrains (в разработке)
- CI/CD Ready - Интеграция с GitLab CI, GitHub Actions, Jenkins
- Docker Support - Полная containerization для легкого deployment
- Auto-Scaling - Поддержка горизонтального масштабирования
- Real-time Updates - Live reload при изменениях кода
- Interactive CLI - Autocomplete, progress bars, colored output

---

🏗️ Architecture

ArchiCore построен по принципам чистой архитектуры с четким разделением слоев:

``
┌─────────────────────────────────────────────────────────────────┐
│ Web Dashboard │
│ (React/Vue-like SPA - public/*.html) │
│ - Project Management - Analytics - Settings - Admin Panel │
└─────────────────────────────────────────────────────────────────┘
↓ HTTPS/API
┌─────────────────────────────────────────────────────────────────┐
│ API Gateway (Express 5) │
│ OAuth, JWT Auth, Rate Limiting, CORS, Helmet, Audit Logging │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────┼─────────────────────┐
↓ ↓ ↓
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Authentication │ │ Project Core │ │ Analysis Engine │
│ - OAuth 2.0 │ │ - Code Indexing │ │ - Impact Analysis│
│ - Email Verify │ │ - AST Parsing │ │ - Risk Assessment│
│ - Device Flow │ │ - Dependency Gr.│ │ - Recommendations│
│ - API Keys │ │ - Metrics │ │ - Dead Code Det. │
└──────────────────┘ └──────────────────┘ └──────────────────┘
↓ ↓ ↓
┌─────────────────────────────────────────────────────────────────┐
│ Semantic Memory Layer │
│ - Vector Embeddings (Jina AI) - Semantic Search (Qdrant) │
│ - Code Similarity - Natural Language Queries │
└─────────────────────────────────────────────────────────────────┘
↓ ↓ ↓
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ PostgreSQL │ │ Redis │ │ Qdrant │
│ - Users, Auth │ │ - Cache Layer │ │ - Vector Store │
│ - Projects │ │ - Sessions │ │ - Embeddings │
│ - Audit Logs │ │ - Rate Limits │ │ - Similarity │
└──────────────────┘ └──────────────────┘ └──────────────────┘
↓ ↓ ↓
┌─────────────────────────────────────────────────────────────────┐
│ AI Orchestration Layer │
│ - Claude (Anthropic) - GPT (OpenAI) - DeepSeek (Budget) │
│ - Context Management - Prompt Optimization - Response Caching │
└─────────────────────────────────────────────────────────────────┘
`

$3

1. User Authentication → OAuth/Email verification → JWT token
2. Project Creation → GitHub sync / Local upload → File indexing
3. Code Indexing → AST Parsing (Tree-sitter) → Symbol extraction → Dependency graph
4. Semantic Embedding → Code chunks → Jina AI → Vector storage (Qdrant)
5. Change Analysis → Modified files → Impact engine → Affected components → Risk assessment
6. AI Query → User question → Context retrieval → LLM (Claude/GPT) → Structured response

---

🛠️ Technology Stack

$3

- Runtime: Node.js 18+ (LTS)
- Language: TypeScript 5.3
- Framework: Express 5.0
- Authentication: Passport.js (OAuth 2.0), JWT
- Validation: Zod, Express Validator

$3

- Primary Database: PostgreSQL 15 (users, projects, audit logs)
- Cache Layer: Redis 7 (sessions, rate limiting, temporary data)
- Vector Database: Qdrant (semantic embeddings, similarity search)

$3

- LLM Providers:
- Anthropic Claude (Opus 4.5, Sonnet 4.5) - Recommended
- OpenAI GPT (GPT-4 Turbo, GPT-4)
- DeepSeek (deepseek-chat, deepseek-coder) - Budget option
- Embeddings: Jina AI (jina-embeddings-v2-base-code)
- Code Parsing: Tree-sitter (40+ languages)

$3

- Architecture: Vanilla JavaScript (SPA-like)
- Styling: Tailwind-like custom CSS
- Build: Vite (development), Custom minification & obfuscation
- State Management: localStorage + fetch API

$3

- Containerization: Docker, Docker Compose
- Reverse Proxy: Nginx (SSL termination, load balancing)
- SSL: Let's Encrypt (auto-renewal)
- CI/CD: GitLab CI/CD
- Monitoring: Custom logging + Audit service

$3

- SMTP: Zoho Mail (verification codes, welcome emails)
- Templates: HTML email templates with branding
- Rate Limiting: 30s cooldown between resends

$3

- Password Hashing: bcrypt (10 rounds)
- Encryption: AES-256-GCM (sensitive data)
- CORS: Configurable whitelist
- Headers: Helmet.js (CSP, HSTS, XSS protection)
- Rate Limiting: Express rate limit (100 req/15min)
- Disposable Email: 180+ domain blacklist

$3

- Package Manager: npm
- Linting: ESLint
- Formatting: Prettier
- Testing: Jest (planned)
- Git Hooks: Husky (planned)

$3

60+ языков через Tree-sitter AST parsing и regex-based analysis:

JavaScript/TypeScript Ecosystem: TypeScript, JavaScript, JSX/TSX, Vue.js, Svelte, Astro
Systems Programming: Go, Rust, Zig, Nim, C, C++
JVM Languages: Java, Kotlin, Scala, Groovy, Clojure
.NET Languages: C#, F#, Visual Basic
Web/Scripting: PHP, Ruby, Perl, Lua
Mobile: Swift, Dart/Flutter, Objective-C
Functional: Haskell, OCaml, Erlang, Elixir, Julia, R
Other: Python, Crystal
Markup/Styles: HTML, CSS, SCSS, Sass, Less, Stylus, XML
Data Formats: JSON, YAML, TOML, INI
Database: SQL, Prisma, GraphQL
Infrastructure: Terraform, Protobuf, Docker, Makefile, CMake
Shell: Bash, Zsh, PowerShell, Batch
Documentation: Markdown, reStructuredText

📖 Complete Language Support Matrix →

---

🚀 Quick Start

$3

- Node.js 18+ (Download)
- Docker (optional but recommended) (Download)
- PostgreSQL 15+ (или через Docker)
- Redis 7+ (или через Docker)

$3

`bash
git clone https://github.com/yourusername/archicore.git
cd archicore
`

$3

`bash
npm install
`

$3

`bash
cp .env.example .env
`

Заполните .env своими ключами:

`env


Server

PORT=3000
NODE_ENV=production
BASE_URL=http://localhost:3000

Database

DATABASE_URL=postgresql://postgres:password@localhost:5432/archicore

Redis

REDIS_URL=redis://localhost:6379

Qdrant Vector DB

QDRANT_URL=http://localhost:6333

AI Providers (выберите один или несколько)

ANTHROPIC_API_KEY=sk-ant-xxx # Рекомендуется для production
OPENAI_API_KEY=sk-xxx # Альтернатива
DEEPSEEK_API_KEY=sk-xxx # Бюджетный вариант
JINA_API_KEY=jina_xxx # Для embeddings

OAuth (опционально)

GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxx
GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx

Email (для verification)

ZOHO_SMTP_USER=noreply@archicore.io
ZOHO_SMTP_PASS=xxx
EMAIL_FROM_ADDRESS=noreply@archicore.io
EMAIL_FROM_NAME=ArchiCore

Security

JWT_SECRET=your-super-secret-jwt-key-change-this
ENCRYPTION_KEY=your-32-char-encryption-key-here
SESSION_SECRET=your-session-secret-change-this

Admin

ADMIN_EMAIL=admin@archicore.io
`

$3

`bash


Запустить все сервисы (PostgreSQL, Redis, Qdrant, ArchiCore)

docker compose up -d

Проверить логи

docker compose logs -f archicore
`

ArchiCore будет доступен на:
- Dashboard: http://localhost:3000
- API: http://localhost:3000/api

$3

`bash


Запустить PostgreSQL

docker run -d --name postgres -p 5432:5432 \
-e POSTGRES_PASSWORD=password \
-e POSTGRES_DB=archicore \
postgres:15

Запустить Redis

docker run -d --name redis -p 6379:6379 redis:7

Запустить Qdrant

docker run -d --name qdrant -p 6333:6333 qdrant/qdrant

Собрать проект

npm run build

Запустить ArchiCore

npm start
`

$3

Откройте браузер: http://localhost:3000

1. Нажмите Sign Up
2. Введите email и password
3. Подтвердите email (код придет на почту)
4. Готово! Вы в системе

---

📦 Installation

$3

Рекомендуется для production. Все сервисы в контейнерах.

`bash


1. Клонировать репозиторий

git clone https://github.com/yourusername/archicore.git
cd archicore

2. Настроить .env

cp .env.example .env
nano .env # Заполнить все ключи

3. Собрать и запустить

docker compose build
docker compose up -d

4. Проверить статус

docker compose ps

5. Просмотр логов

docker compose logs -f archicore

6. Остановить

docker compose down
`

Docker Compose включает:
- ArchiCore (Node.js app)
- PostgreSQL 15
- Redis 7
- Qdrant vector DB
- Nginx reverse proxy (если настроен)

$3

Для локальной разработки без Docker.

#### Step 1: Install Node.js

`bash


Ubuntu/Debian

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

macOS (Homebrew)

brew install node@18

Windows

Download from https://nodejs.org/

`

#### Step 2: Install Databases

PostgreSQL:
`bash


Ubuntu/Debian

sudo apt install postgresql postgresql-contrib

macOS

brew install postgresql@15
brew services start postgresql@15

Windows

Download from https://www.postgresql.org/download/windows/

`

Redis:
`bash


Ubuntu/Debian

sudo apt install redis-server
sudo systemctl start redis

macOS

brew install redis
brew services start redis

Windows

Download from https://github.com/microsoftarchive/redis/releases

`

Qdrant:
`bash


Через Docker (рекомендуется)

docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant

Или скачать binary

./start-qdrant.sh # Linux/Mac
start-qdrant.bat # Windows
`

#### Step 3: Setup Database

`bash


Создать базу данных

createdb archicore

Или через psql

psql -U postgres
CREATE DATABASE archicore;
\q
`

#### Step 4: Install ArchiCore

`bash


Клонировать и установить зависимости

git clone https://github.com/yourusername/archicore.git
cd archicore
npm install

Настроить .env

cp .env.example .env
nano .env

Собрать проект

npm run build

Запустить

npm start
`

#### Step 5: Verify Installation

`bash


Проверить доступность API

curl http://localhost:3000/health

Должен вернуть:

{"status":"ok","version":"0.3.1"}

`

$3

Установить ArchiCore CLI глобально:

`bash
npm install -g archicore

Авторизоваться

archicore login

Начать использование

archicore projects list
`

---

💻 Usage

ArchiCore предоставляет три способа взаимодействия: Web Dashboard, CLI Tool и REST API.

$3

#### 1. Landing Page (/)

Главная страница с описанием продукта, ценами и возможностями.

Features:
- Hero section с CTA
- Features overview
- Pricing plans (Free, Team, Pro, Enterprise)
- Footer с navigation

#### 2. Authentication (/auth)

Страница входа/регистрации.

Login:
`
1. Email + Password
2. OAuth (Google / GitHub)
`

Sign Up:
`
1. Enter email + password
2. Verify email (6-digit code sent via SMTP)
3. Automatic login after verification
`

Features:
- Email verification required
- Disposable email blocked (180+ domains)
- Device flow for CLI auth
- Password recovery (planned)

#### 3. Dashboard (/dashboard)

Главный рабочий интерфейс после авторизации.

Sections:

Projects:
- Create new project (name, description, GitHub URL)
- List all projects with stats
- Select active project
- Delete projects

Project Actions:
`
├── Index Project - Анализ кода и построение графа
├── Full Analysis - Полный отчет (metrics, security, duplication, dead code)
├── Security Analysis - Проверка уязвимостей
├── Dead Code Detection - Поиск неиспользуемого кода
├── Code Duplication - Поиск дублирования
├── Metrics Report - Code metrics (complexity, LOC, maintainability)
├── Refactoring Suggestions - AI рекомендации
└── Export Data - JSON/HTML/Markdown/CSV
`

Code Search:
- Semantic search: "функции для обработки платежей"
- Results with file paths, line numbers, relevance scores

AI Architect:
- Ask questions: "Как организована аутентификация?"
- Context-aware answers based on your codebase
- Architecture recommendations

Account Section:
- Profile information
- Subscription tier (Free/Team/Pro/Enterprise)
- Usage statistics (API calls, projects, storage)
- Logout

#### 4. Pricing Page (/pricing)

Тарифные планы с подробным описанием.

Plans:

| Feature | Free | Team | Pro | Enterprise |
|---------|------|------|-----|------------|
| Price | $0 | $249/mo | $599/mo | Custom |
| Repositories | 1 | 3 | 10 | Unlimited |
| Developers | 1 | 5 | 20 | Unlimited |
| Analysis | Snapshot | Regular | PR-level | Continuous |
| API Access | ❌ | ❌ | ✅ | ✅ |
| GitHub/GitLab Integration | ❌ | ❌ | ✅ | ✅ |
| Data Retention | 7 days | 14 days | 30 days | Custom |
| Support | Community | Email | Priority | Dedicated manager |

#### 5. Admin Panel (/admin)

Панель администратора (только для admin role).

Features:
- Users Management: List, search, edit, delete users
- Tier Management: Change user subscription tiers
- Statistics: Total users, projects, API calls, storage
- Audit Logs: View all user actions with filters
- System Settings:
- Maintenance mode toggle
- Email configuration test
- Cache management (clear Redis/memory)
- System backup & restore
- Factory reset
- Export: Export all system data (JSON/CSV)

#### 6. Legal Pages

- Privacy Policy (/privacy.html)
- Terms of Service (/terms.html)
- Security (/security.html)

---

$3

ArchiCore CLI - мощный инструмент для автоматизации и CI/CD интеграции.

#### Installation

`bash


Установить глобально

npm install -g archicore

Или использовать локально

npx archicore [command]
`

#### Authentication

`bash


Device Flow (открывает браузер для авторизации)

archicore login

Введите код из терминала на странице авторизации

После успеха токен сохраняется в ~/.archicore/config.json

`

#### Project Management

`bash


Список проектов

archicore projects list

Создать проект

archicore projects create --name "My App" --github "https://github.com/user/repo"

Выбрать активный проект

archicore projects select

Удалить проект

archicore projects delete --id abc123
`

#### Code Analysis

`bash


Индексировать проект (AST + граф зависимостей)

archicore index --dir /path/to/project

Полный анализ

archicore full-analysis

Анализ безопасности

archicore security

Поиск мертвого кода

archicore dead-code

Метрики кода

archicore metrics

Дублирование кода

archicore duplication

Рефакторинг рекомендации

archicore refactoring
`

#### Semantic Search

`bash


Поиск по смыслу

archicore search --query "функции валидации email" --limit 10

Результат:

🔍 RESULTS:

#

1. src/utils/validators.ts:45 (relevance: 94.2%)

export function validateEmail(email: string): boolean {

#

2. src/auth/email-validator.ts:12 (relevance: 89.7%)

class EmailValidator {

`

#### AI Architect

`bash


Задать вопрос

archicore ask --question "Как организована работа с платежами?"

Анализ изменений

archicore analyze \
--description "Добавить новый метод оплаты" \
--files "src/payments/processor.ts" \
--type "feature"

Результат:

⚠️ AFFECTED COMPONENTS: 23

🔴 CRITICAL: 5

🟠 HIGH: 11

🟡 MEDIUM: 7

#

RISKS:

[HIGH] Breaking change in PaymentProcessor interface

[MEDIUM] New dependencies added to payment flow

#

RECOMMENDATIONS:

✅ Add backward compatibility wrapper

✅ Update API documentation

✅ Write integration tests for new method

`

#### Export

`bash


Экспорт результатов анализа


archicore export --format json --output analysis.json
archicore export --format html --output report.html
archicore export --format markdown --output ANALYSIS.md
archicore export --format csv --output metrics.csv
`

#### Interactive Mode

`bash


Интерактивный режим с autocomplete

archicore chat

Внутри появится меню команд:

> /help - Показать доступные команды

> /search - Семантический поиск

> /ask - Вопрос AI архитектору

> /analyze - Анализ изменений

> /metrics - Метрики проекта

> /exit - Выход

`

📖 Complete CLI Documentation →

---

$3

Полное REST API для интеграции с CI/CD, webhooks, custom tools.

#### Base URL

`
Production: https://api.archicore.io
Development: http://localhost:3000/api
`

#### Authentication

JWT Token:
`bash


Login

curl -X POST https://api.archicore.io/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","password":"secret"}'

Response:

{"success":true,"token":"eyJhbGc...","user":{...}}

Use token in requests

curl -H "Authorization: Bearer eyJhbGc..." \
https://api.archicore.io/projects
`

API Key:
`bash


Create API key (через dashboard /developer)

curl -X POST https://api.archicore.io/developer/keys \
-H "Authorization: Bearer YOUR_JWT" \
-d '{"name":"CI/CD Key","expiresInDays":365}'

Use API key

curl -H "X-API-Key: ak_xxx" \
https://api.archicore.io/projects
`

#### Endpoints Overview

Authentication:
`
POST /api/auth/register - Регистрация
POST /api/auth/login - Вход
POST /api/auth/logout - Выход
GET /api/auth/me - Текущий пользователь
GET /api/auth/usage - Статистика использования
POST /api/auth/send-verification-code - Отправить код верификации
POST /api/auth/verify-email - Подтвердить email
`

OAuth:
`
GET /api/auth/oauth/google - Начать Google OAuth
GET /api/auth/oauth/google/callback - Google callback
GET /api/auth/oauth/github - Начать GitHub OAuth
GET /api/auth/oauth/github/callback - GitHub callback
`

Device Flow (CLI):
`
POST /api/auth/device/code - Получить device code
POST /api/auth/device/token - Обменять код на токен
GET /api/auth/device/verify/:code - Проверить код
POST /api/auth/device/authorize - Авторизовать устройство
`

Projects:
`
GET /api/projects - Список проектов
POST /api/projects - Создать проект
GET /api/projects/:id - Получить проект
PUT /api/projects/:id - Обновить проект
DELETE /api/projects/:id - Удалить проект
POST /api/projects/:id/index - Индексировать код
GET /api/projects/:id/architecture - Архитектурная информация
GET /api/projects/:id/graph - Граф зависимостей
GET /api/projects/:id/metrics - Метрики кода
`

Analysis:
`
POST /api/analyze/impact - Анализ влияния изменений
POST /api/analyze/security - Анализ безопасности
POST /api/analyze/full - Полный анализ
POST /api/analyze/dead-code - Мертвый код
POST /api/analyze/duplication - Дублирование
POST /api/analyze/refactoring - Рекомендации по рефакторингу
`

AI:
`
POST /api/ai/search - Семантический поиск
POST /api/ai/ask - Вопрос AI архитектору
POST /api/ai/simulate - Симуляция изменений
`

GitHub:
`
GET /api/github/auth - GitHub OAuth
GET /api/github/callback - GitHub callback
GET /api/github/repositories - Список репозиториев
POST /api/github/webhooks - Создать webhook
`

Admin:
`
GET /api/admin/users - Список пользователей
PUT /api/admin/users/:id/tier - Изменить tier
GET /api/admin/stats - Статистика системы
GET /api/admin/audit-logs - Аудит логи
GET /api/admin/settings - Настройки системы
POST /api/admin/settings - Обновить настройки
POST /api/admin/test-email - Тест email
POST /api/admin/maintenance - Включить maintenance mode
GET /api/admin/export/all - Экспорт всех данных
`

Developer:
`
GET /api/developer/keys - Список API ключей
POST /api/developer/keys - Создать API ключ
DELETE /api/developer/keys/:id - Удалить API ключ
POST /api/developer/keys/:id/revoke - Отозвать API ключ
`

Upload & Utilities:
`
POST /api/upload - Загрузить файлы проекта
POST /api/report-issue - Отправить bug report
GET /api/tasks/:taskId - Статус задачи
GET /api/tasks/:taskId/stream - WebSocket progress updates
`

📖 Complete API Documentation →

#### Example: Analyze Impact

`bash
curl -X POST https://api.archicore.io/analyze/impact \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"projectId": "proj_abc123",
"change": {
"type": "modify",
"description": "Рефакторинг AuthService",
"files": ["src/services/auth-service.ts"],
"symbols": ["AuthService", "login", "register"]
}
}'
`

Response:
`json
{
"success": true,
"impact": {
"affectedNodes": [
{
"id": "AuthController",
"file": "src/controllers/auth.ts",
"severity": "critical",
"reason": "Direct dependency on modified AuthService"
},
{
"id": "UserService",
"file": "src/services/user-service.ts",
"severity": "high",
"reason": "Calls AuthService.login()"
}
],
"risks": [
{
"severity": "high",
"message": "Breaking change in public API",
"recommendation": "Add deprecation warnings before removing methods"
}
],
"recommendations": [
"Review 15 affected components",
"Add integration tests for auth flow",
"Update API documentation"
],
"summary": {
"total": 15,
"critical": 3,
"high": 7,
"medium": 4,
"low": 1
}
}
}
`

---

🔐 Authentication & Security

ArchiCore реализует многоуровневую систему безопасности корпоративного уровня.

$3

#### 1. Email + Password

Registration Flow:
`
1. User submits email + password
2. System checks disposable email (180+ blocked domains)
3. Sends 6-digit verification code via SMTP (Zoho)
4. User enters code (10-minute expiry)
5. Password hashed with bcrypt (10 rounds)
6. User created, JWT token issued
7. Welcome email sent
`

Login Flow:
`
1. User submits email + password
2. Password verified with bcrypt
3. JWT token issued (24h expiry)
4. Refresh token stored in DB (30d expiry)
5. Audit log created
`

#### 2. OAuth 2.0 (Google, GitHub)

Flow:
`
1. User clicks "Continue with Google/GitHub"
2. Redirected to provider authorization page
3. User grants permissions
4. Provider redirects to /callback with code
5. ArchiCore exchanges code for access token
6. Fetches user profile (email, name, avatar)
7. Creates user if first login OR logs in existing
8. JWT token issued
9. Redirected to dashboard with token in URL
10. Frontend saves token to localStorage
`

Implemented Providers:
- ✅ Google OAuth 2.0 (scope: profile, email)
- ✅ GitHub OAuth 2.0 (scope: user:email)

#### 3. Device Flow (CLI)

Flow for CLI authentication:
`
1. CLI requests device code: POST /api/auth/device/code
2. Server returns: {device_code, user_code, verification_url}
3. CLI displays: "Go to https://archicore.io/auth/device and enter: ABCD-1234"
4. User opens browser, enters code
5. User authorizes device
6. CLI polls: POST /api/auth/device/token with device_code
7. On success, receives JWT token
8. Token saved to ~/.archicore/config.json
`

#### 4. API Keys

For programmatic access:
`
1. User creates API key via dashboard (/developer)
2. Key format: ak_xxxxxxxxxxxxxxxxxx (40 chars)
3. Key stored hashed in database
4. Use in requests: X-API-Key: ak_xxx
5. Keys can be revoked or deleted
6. Supports expiration (optional)
`

$3

#### Password Security
- Hashing: bcrypt with 10 salt rounds
- Validation: Min 8 chars, complexity requirements (planned)
- Reset: Email-based password reset (planned)

#### JWT Tokens
- Algorithm: HS256
- Expiry: 24 hours (configurable)
- Payload: userId, email, role, tier
- Secret: From environment variable JWT_SECRET
- Refresh: Refresh tokens with 30d expiry (planned)

#### Disposable Email Protection
- Database: 180+ temporary email domains
- Blocked services: 10minutemail, guerrillamail, mailinator, yopmail, temp-mail, etc.
- Check points: Registration, email verification, OAuth
- Error message: "Temporary/disposable email addresses are not allowed"

#### Email Verification
- Code: 6 random digits
- Expiry: 10 minutes
- Storage: In-memory Map (auto-cleanup on expiry)
- Rate limit: 30 seconds between resends
- Transport: SMTP via Zoho (TLS, port 587)
- Templates: Branded HTML emails

#### Rate Limiting
- Global: 100 requests per 15 minutes per IP
- Auth endpoints: 5 login attempts per 15 minutes
- Email sending: 3 codes per hour per email
- Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

#### Encryption
- Algorithm: AES-256-GCM
- Key: From environment ENCRYPTION_KEY (32 chars)
- Use cases: Sensitive user data, API keys in DB, OAuth tokens

#### Audit Logging
All actions logged:
- Authentication (login, logout, register, OAuth)
- Project operations (create, update, delete)
- Analysis requests
- Admin actions (user management, settings changes)
- API key operations

Log fields:
- userId, username, action, timestamp, ip, userAgent
- success/failure, errorMessage
- details (JSON with context-specific data)

#### CORS & Headers
- CORS: Configurable whitelist (production), allow-all (development)
- Helmet.js: CSP, HSTS, X-Frame-Options, XSS Protection
- Gzip: Response compression

#### HTTPS
- Production: Let's Encrypt SSL certificates
- Auto-renewal: Certbot cron job
- Redirect: HTTP → HTTPS (nginx)
- HSTS: Strict-Transport-Security header

---

⚙️ Configuration

$3

Полный список переменных окружения:

`env


═══════════════════════════════════════════════════════════

SERVER CONFIGURATION

═══════════════════════════════════════════════════════════

PORT=3000
NODE_ENV=production
BASE_URL=https://archicore.io

═══════════════════════════════════════════════════════════

DATABASE

═══════════════════════════════════════════════════════════

DATABASE_URL=postgresql://user:password@localhost:5432/archicore
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=20

═══════════════════════════════════════════════════════════

REDIS CACHE

═══════════════════════════════════════════════════════════

REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=
REDIS_DB=0

═══════════════════════════════════════════════════════════

QDRANT VECTOR DATABASE

═══════════════════════════════════════════════════════════

QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=
QDRANT_COLLECTION_NAME=archicore

═══════════════════════════════════════════════════════════

AI PROVIDERS

═══════════════════════════════════════════════════════════

Anthropic Claude (Рекомендуется)

ANTHROPIC_API_KEY=sk-ant-api03-xxx
ANTHROPIC_MODEL=claude-sonnet-4-20250514

Доступные модели:

- claude-opus-4-20250514 (самый умный, дорогой)

- claude-sonnet-4-20250514 (баланс качество/цена) ⭐

- claude-haiku-4-20250514 (быстрый, дешевый)

OpenAI GPT

OPENAI_API_KEY=sk-xxx
OPENAI_MODEL=gpt-4-turbo-preview

Доступные модели:

- gpt-4-turbo-preview (новый GPT-4 Turbo)

- gpt-4 (стандартный GPT-4)

- gpt-3.5-turbo (быстрый, дешевый)

DeepSeek (Бюджетный вариант)

DEEPSEEK_API_KEY=sk-xxx
DEEPSEEK_MODEL=deepseek-chat

Доступные модели:

- deepseek-chat (общего назначения)

- deepseek-coder (для кода) ⭐

Jina AI (Embeddings)

JINA_API_KEY=jina_xxx
JINA_MODEL=jina-embeddings-v2-base-code

═══════════════════════════════════════════════════════════

OAUTH PROVIDERS

═══════════════════════════════════════════════════════════

Google OAuth 2.0

GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxx
GOOGLE_CALLBACK_URL=https://archicore.io/api/auth/oauth/google/callback

GitHub OAuth

GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx
GITHUB_CALLBACK_URL=https://archicore.io/api/auth/oauth/github/callback

═══════════════════════════════════════════════════════════

EMAIL (SMTP)

═══════════════════════════════════════════════════════════

SMTP_HOST=smtp.zoho.com
SMTP_PORT=587
SMTP_SECURE=false
ZOHO_SMTP_USER=noreply@archicore.io
ZOHO_SMTP_PASS=xxx
EMAIL_FROM_ADDRESS=noreply@archicore.io
EMAIL_FROM_NAME=ArchiCore

═══════════════════════════════════════════════════════════

SECURITY

═══════════════════════════════════════════════════════════

JWT_SECRET=your-super-secret-jwt-key-min-32-chars
JWT_EXPIRY=24h
ENCRYPTION_KEY=your-32-character-encryption-key
SESSION_SECRET=your-session-secret-min-32-chars

CORS

CORS_ORIGIN=https://archicore.io,https://app.archicore.io
CORS_CREDENTIALS=true

Rate Limiting

RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

═══════════════════════════════════════════════════════════

ADMIN

═══════════════════════════════════════════════════════════

ADMIN_EMAIL=admin@archicore.io
ADMIN_PASSWORD=change-this-in-production

═══════════════════════════════════════════════════════════

FEATURES (Optional)

═══════════════════════════════════════════════════════════

ENABLE_GITHUB_INTEGRATION=true
ENABLE_WEBHOOKS=true
ENABLE_METRICS=true
ENABLE_ANALYTICS=true

═══════════════════════════════════════════════════════════

LOGGING

═══════════════════════════════════════════════════════════

LOG_LEVEL=info

Levels: error, warn, info, debug, trace

LOG_FORMAT=json

Formats: json, pretty

`

$3

Файл .archicore/architecture.json для определения правил архитектуры:

`json
{
"boundedContexts": [
{
"id": "auth",
"name": "Authentication Context",
"description": "User authentication and authorization",
"modules": ["src/server/routes/auth.ts", "src/server/services/auth-service.ts"],
"dependencies": [],
"prohibitedDependencies": ["src/ui", "src/business-logic"]
},
{
"id": "core",
"name": "Core Business Logic",
"description": "Main business domain",
"modules": ["src/core"],
"dependencies": ["auth"],
"prohibitedDependencies": ["src/infrastructure"]
}
],
"entities": [
{
"id": "user",
"name": "User",
"context": "auth",
"properties": ["id", "email", "username", "role"],
"relationships": [
{"entity": "project", "type": "one-to-many"}
],
"invariants": [
"email must be unique",
"email must be verified before login"
]
}
],
"rules": [
{
"id": "no-circular-deps",
"description": "No circular dependencies allowed",
"severity": "error",
"check": "circular-dependencies"
},
{
"id": "layer-separation",
"description": "UI layer cannot depend on database layer",
"severity": "error",
"check": "layer-violation",
"config": {
"layers": ["ui", "business", "data"],
"allowedDependencies": {
"ui": ["business"],
"business": ["data"],
"data": []
}
}
}
],
"invariants": [
"All API endpoints must have rate limiting",
"All user actions must be logged in audit",
"Passwords must be hashed with bcrypt"
]
}
`

$3

Пример production docker-compose.yml:

`yaml
version: '3.9'

services:
# ArchiCore Application
archicore:
build: .
container_name: archicore
restart: unless-stopped
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- DATABASE_URL=postgresql://postgres:${DB_PASSWORD}@postgres:5432/archicore
- REDIS_URL=redis://redis:6379
- QDRANT_URL=http://qdrant:6333
env_file:
- .env
depends_on:
- postgres
- redis
- qdrant
volumes:
- ./data:/app/data
networks:
- archicore-network
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3

# PostgreSQL Database
postgres:
image: postgres:15-alpine
container_name: archicore-postgres
restart: unless-stopped
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=${DB_PASSWORD}
- POSTGRES_DB=archicore
volumes:
- postgres-data:/var/lib/postgresql/data
networks:
- archicore-network
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5

# Redis Cache
redis:
image: redis:7-alpine
container_name: archicore-redis
restart: unless-stopped
command: redis-server --appendonly yes
volumes:
- redis-data:/data
networks:
- archicore-network
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 3s
retries: 3

# Qdrant Vector Database
qdrant:
image: qdrant/qdrant:latest
container_name: archicore-qdrant
restart: unless-stopped
volumes:
- qdrant-data:/qdrant/storage
networks:
- archicore-network
healthcheck:
test: ["CMD-SHELL", "timeout 1 bash -c ' interval: 10s
timeout: 5s
retries: 3

# Nginx Reverse Proxy (Optional)
nginx:
image: nginx:alpine
container_name: archicore-nginx
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./ssl:/etc/nginx/ssl:ro
depends_on:
- archicore
networks:
- archicore-network

volumes:
postgres-data:
redis-data:
qdrant-data:

networks:
archicore-network:
driver: bridge
`

---

🚢 Deployment

$3

Полная инструкция для deployment на production сервер.

#### Prerequisites

- Ubuntu 20.04+ / Debian 11+ / CentOS 8+
- Root или sudo доступ
- Домен с настроенным DNS (A record → server IP)

#### Step 1: Prepare Server

`bash


Обновить систему

sudo apt update && sudo apt upgrade -y

Установить Docker

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Установить Docker Compose

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Установить Nginx

sudo apt install nginx -y

Установить Certbot (Let's Encrypt)

sudo apt install certbot python3-certbot-nginx -y
`

#### Step 2: Clone & Configure

`bash


Клонировать репозиторий

cd /opt
sudo git clone https://github.com/yourusername/archicore.git
cd archicore

Создать .env

sudo cp .env.example .env
sudo nano .env # Заполнить production значения

Установить правильные permissions

sudo chown -R $USER:$USER /opt/archicore
`

#### Step 3: SSL Certificate

`bash


Получить SSL сертификат

sudo certbot --nginx -d archicore.io -d www.archicore.io -d api.archicore.io -d docs.archicore.io

Auto-renewal настроен автоматически через systemd timer

Проверить:

sudo systemctl status certbot.timer
`

#### Step 4: Nginx Configuration

`bash


Создать конфиг

sudo nano /etc/nginx/sites-available/archicore

Вставить:

`

`nginx


Main app (archicore.io)

server {
listen 443 ssl http2;
server_name archicore.io www.archicore.io;

ssl_certificate /etc/letsencrypt/live/archicore.io/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/archicore.io/privkey.pem;

location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
}
}

API subdomain (api.archicore.io)

server {
listen 443 ssl http2;
server_name api.archicore.io;

ssl_certificate /etc/letsencrypt/live/archicore.io/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/archicore.io/privkey.pem;

location / {
proxy_pass http://localhost:3000/api;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}

Redirect HTTP to HTTPS

server {
listen 80;
server_name archicore.io www.archicore.io api.archicore.io;
return 301 https://$host$request_uri;
}
`

`bash


Включить сайт


sudo ln -s /etc/nginx/sites-available/archicore /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
`

#### Step 5: Start Services

`bash
cd /opt/archicore

Собрать образы

sudo docker compose build

Запустить все сервисы

sudo docker compose up -d

Проверить статус

sudo docker compose ps
sudo docker compose logs -f archicore
`

#### Step 6: Setup Systemd Service (Optional)

Для автоматического запуска при перезагрузке:

`bash
sudo nano /etc/systemd/system/archicore.service
`

`ini
[Unit]
Description=ArchiCore Application
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/archicore
ExecStart=/usr/local/bin/docker-compose up -d
ExecStop=/usr/local/bin/docker-compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target
`

`bash
sudo systemctl enable archicore
sudo systemctl start archicore
`

#### Step 7: Monitoring & Logs

`bash


Просмотр логов

sudo docker compose logs -f archicore
sudo docker compose logs -f postgres
sudo docker compose logs -f redis

Статус контейнеров

sudo docker compose ps

Использование ресурсов

sudo docker stats

Nginx access log

sudo tail -f /var/log/nginx/access.log

Nginx error log

sudo tail -f /var/log/nginx/error.log
`

#### Step 8: Backup Strategy

`bash


Создать backup скрипт


sudo nano /opt/archicore/backup.sh
`

`bash
#!/bin/bash
BACKUP_DIR=/opt/backups/archicore
DATE=$(date +%Y%m%d_%H%M%S)

Создать директорию

mkdir -p $BACKUP_DIR

Backup PostgreSQL

docker exec archicore-postgres pg_dump -U postgres archicore | gzip > $BACKUP_DIR/postgres_$DATE.sql.gz

Backup Redis

docker exec archicore-redis redis-cli BGSAVE
docker cp archicore-redis:/data/dump.rdb $BACKUP_DIR/redis_$DATE.rdb

Backup Qdrant

docker cp archicore-qdrant:/qdrant/storage $BACKUP_DIR/qdrant_$DATE

Удалить старые бэкапы (>30 дней)

find $BACKUP_DIR -name "*.gz" -mtime +30 -delete

echo "Backup completed: $DATE"
`

`bash


Сделать исполняемым

sudo chmod +x /opt/archicore/backup.sh

Добавить в cron (ежедневно в 2 AM)

sudo crontab -e
0 2 * /opt/archicore/backup.sh >> /var/log/archicore-backup.log 2>&1
`

#### Step 9: Update Procedure

`bash


Обновление ArchiCore до новой версии

cd /opt/archicore
sudo git pull origin main
sudo docker compose build
sudo docker compose up -d

Откатиться к предыдущей версии при проблемах

sudo git log --oneline # Найти хеш коммита
sudo git checkout
sudo docker compose build
sudo docker compose up -d
`

$3

Пример .gitlab-ci.yml:

`yaml
stages:
- test
- build
- deploy

variables:
DOCKER_DRIVER: overlay2
DOCKER_TLS_CERTDIR: "/certs"

Run tests

test:
stage: test
image: node:18
cache:
paths:
- node_modules/
script:
- npm ci
- npm run lint
- npm run test # Когда тесты будут написаны
only:
- merge_requests
- main

Build Docker image

build:
stage: build
image: docker:latest
services:
- docker:dind
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
- docker build -t $CI_REGISTRY_IMAGE:latest .
- docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
- docker push $CI_REGISTRY_IMAGE:latest
only:
- main

Deploy to production

deploy_production:
stage: deploy
image: alpine:latest
before_script:
- apk add --no-cache openssh-client
- eval $(ssh-agent -s)
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
- ssh-keyscan $PRODUCTION_SERVER >> ~/.ssh/known_hosts
script:
- ssh $PRODUCTION_USER@$PRODUCTION_SERVER "cd /opt/archicore && git pull && docker compose pull && docker compose up -d"
only:
- main
when: manual
`

---

📚 API Reference

$3

#### POST /api/auth/register

Регистрация нового пользователя.

Request:
`json
{
"email": "user@example.com",
"password": "SecurePass123!",
"username": "johndoe"
}
`

Response (200):
`json
{
"success": true,
"message": "Verification code sent to your email"
}
`

Errors:
- 400 - Invalid email/password, disposable email blocked
- 409 - Email already exists

---

#### POST /api/auth/verify-email

Подтверждение email с verification code.

Request:
`json
{
"email": "user@example.com",
"code": "123456"
}
`

Response (200):
`json
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"username": "johndoe",
"role": "user",
"tier": "free",
"createdAt": "2026-01-17T10:00:00Z"
}
}
`

Errors:
- 400 - Invalid or expired code
- 404 - Email not found

---

#### POST /api/auth/login

Вход с email и паролем.

Request:
`json
{
"email": "user@example.com",
"password": "SecurePass123!"
}
`

Response (200):
`json
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"username": "johndoe",
"role": "user",
"tier": "pro",
"createdAt": "2026-01-17T10:00:00Z"
}
}
`

Errors:
- 401 - Invalid credentials
- 403 - Email not verified

---

$3

#### GET /api/projects

Получить список проектов пользователя.

Headers:
`
Authorization: Bearer
`

Response (200):
`json
{
"success": true,
"projects": [
{
"id": "proj_abc123",
"name": "E-commerce Platform",
"description": "Online store backend",
"githubUrl": "https://github.com/user/ecommerce",
"language": "TypeScript",
"filesCount": 243,
"linesOfCode": 15420,
"indexed": true,
"lastIndexed": "2026-01-17T12:00:00Z",
"createdAt": "2026-01-15T10:00:00Z"
}
]
}
`

---

#### POST /api/projects

Создать новый проект.

Request:
`json
{
"name": "E-commerce Platform",
"description": "Online store backend",
"githubUrl": "https://github.com/user/ecommerce"
}
`

Response (201):
`json
{
"success": true,
"project": {
"id": "proj_abc123",
"name": "E-commerce Platform",
"description": "Online store backend",
"githubUrl": "https://github.com/user/ecommerce",
"indexed": false,
"createdAt": "2026-01-17T12:00:00Z"
}
}
`

---

#### POST /api/projects/:id/index

Индексировать код проекта.

Response (200):
`json
{
"success": true,
"stats": {
"filesProcessed": 243,
"symbolsExtracted": 1854,
"graphNodes": 2107,
"graphEdges": 4523,
"vectorsCreated": 1854,
"languages": {
"TypeScript": 180,
"JavaScript": 45,
"JSON": 18
},
"symbols": {
"function": 892,
"class": 156,
"interface": 234,
"variable": 572
}
}
}
`

---

$3

#### POST /api/analyze/impact

Анализ влияния изменений.

Request:
`json
{
"projectId": "proj_abc123",
"change": {
"type": "modify",
"description": "Refactor payment service",
"files": ["src/services/payment-service.ts"],
"symbols": ["PaymentService", "processPayment"]
}
}
`

Response (200):
`json
{
"success": true,
"impact": {
"affectedComponents": [
{
"id": "PaymentController",
"file": "src/controllers/payment.ts",
"line": 45,
"severity": "critical",
"reason": "Direct dependency on PaymentService"
},
{
"id": "OrderService",
"file": "src/services/order-service.ts",
"line": 120,
"severity": "high",
"reason": "Calls PaymentService.processPayment()"
}
],
"risks": [
{
"severity": "critical",
"message": "Breaking change in public API",
"recommendation": "Add deprecation warnings"
},
{
"severity": "high",
"message": "12 components depend on modified code",
"recommendation": "Review all affected components"
}
],
"recommendations": [
"Add integration tests for payment flow",
"Update API documentation",
"Notify team about breaking changes"
],
"summary": {
"total": 23,
"critical": 3,
"high": 12,
"medium": 6,
"low": 2
}
}
}
`

---

#### POST /api/analyze/security

Анализ безопасности кода.

Response (200):
`json
{
"success": true,
"findings": [
{
"severity": "critical",
"type": "SQL Injection",
"file": "src/database/users.ts",
"line": 45,
"message": "Unsanitized user input in SQL query",
"recommendation": "Use parameterized queries"
},
{
"severity": "high",
"type": "XSS Vulnerability",
"file": "src/views/profile.ts",
"line": 23,
"message": "Unescaped user content in HTML",
"recommendation": "Use proper HTML escaping"
}
],
"summary": {
"critical": 1,
"high": 3,
"medium": 7,
"low": 12,
"info": 5
}
}
`

---

$3

#### POST /api/ai/search

Семантический поиск кода.

Request:
`json
{
"projectId": "proj_abc123",
"query": "функции валидации email",
"limit": 5
}
`

Response (200):
`json
{
"success": true,
"results": [
{
"file": "src/utils/validators.ts",
"line": 45,
"code": "export function validateEmail(email: string): boolean {",
"relevance": 0.942,
"context": "Email validation utility"
},
{
"file": "src/auth/email-validator.ts",
"line": 12,
"code": "class EmailValidator implements IValidator {",
"relevance": 0.897,
"context": "Authentication email validation"
}
]
}
`

---

#### POST /api/ai/ask

Задать вопрос AI архитектору.

Request:
`json
{
"projectId": "proj_abc123",
"question": "Как организована аутентификация в системе?"
}
`

Response (200):
`json
{
"success": true,
"answer": "В системе используется многоуровневая аутентификация:\n\n1. JWT Tokens - основной механизм (src/auth/jwt.ts)\n2. OAuth 2.0 - Google и GitHub (src/auth/oauth/)\n3. Email Verification - подтверждение через SMTP (src/auth/email-verify.ts)\n\nПоток аутентификации:\n- User → Email+Password OR OAuth\n- Verification code → Email\n- Code validation → JWT token\n- Token → Stored in localStorage\n- Requests → Authorization: Bearer \n\nБезопасность:\n- Passwords: bcrypt (10 rounds)\n- Tokens: HS256, 24h expiry\n- Rate limiting: 5 attempts/15min",
"sources": [
{"file": "src/auth/jwt.ts", "relevance": 0.95},
{"file": "src/auth/oauth/google.ts", "relevance": 0.88},
{"file": "src/auth/email-verify.ts", "relevance": 0.91}
]
}
`

---

🛠️ Development

$3

`bash


Clone repository

git clone https://github.com/yourusername/archicore.git
cd archicore

Install dependencies

npm install

Start databases (Docker)

docker compose -f docker-compose.dev.yml up -d

Copy env file

cp .env.example .env

Fill in development keys

nano .env

Start in development mode (with hot reload)

npm run dev
`

$3

`
archicore/
├── public/ # Frontend (SPA-like vanilla JS)
│ ├── index.html # Dashboard
│ ├── auth.html # Authentication page
│ ├── pricing.html # Pricing page
│ ├── admin.html # Admin panel
│ ├── privacy.html # Privacy policy
│ ├── terms.html # Terms of service
│ └── assets/ # Static assets
├── src/
│ ├── server/ # Backend (Express)
│ │ ├── routes/ # API routes
│ │ │ ├── auth.ts # Authentication endpoints
│ │ │ ├── oauth.ts # OAuth flows
│ │ │ ├── projects.ts # Project management
│ │ │ ├── analyze.ts # Analysis endpoints
│ │ │ ├── ai.ts # AI endpoints
│ │ │ ├── admin.ts # Admin endpoints
│ │ │ └── developer.ts # API keys management
│ │ ├── services/ # Business logic
│ │ │ ├── auth-service.ts
│ │ │ ├── audit-service.ts
│ │ │ ├── database.ts
│ │ │ ├── email-service.ts
│ │ │ └── encryption.ts
│ │ ├── config/ # Configuration
│ │ │ └── passport.ts # OAuth strategies
│ │ └── middleware/ # Express middleware
│ ├── code-index/ # Code indexing engine
│ │ ├── index.ts # Main indexer
│ │ ├── ast-parser.ts # Tree-sitter parser
│ │ ├── symbol-extractor.ts
│ │ └── dependency-graph.ts
│ ├── semantic-memory/ # Vector DB layer
│ │ ├── index.ts
│ │ ├── embedding-service.ts # Jina AI
│ │ └── vector-store.ts # Qdrant
│ ├── impact-engine/ # Change impact analysis
│ │ └── index.ts
│ ├── orchestrator/ # AI orchestration
│ │ └── index.ts # Claude/GPT/DeepSeek
│ ├── analyzers/ # Code analyzers
│ │ ├── security.ts
│ │ ├── dead-code.ts
│ │ ├── duplication.ts
│ │ └── metrics.ts
│ ├── cli/ # CLI tool
│ │ └── commands/
│ ├── types/ # TypeScript types
│ └── utils/ # Utilities
├── .archicore/ # Architecture config
│ └── architecture.json
├── docker-compose.yml # Production compose
├── docker-compose.dev.yml # Development compose
├── Dockerfile
├── package.json
├── tsconfig.json
└── README.md
`

$3

`bash


Development

npm run dev # Start with hot reload (tsx watch)
npm run dev:debug # Start with debugger

Build

npm run build # Compile TypeScript
npm run build:frontend # Minify & obfuscate frontend
npm run build:all # Build backend + frontend

Production

npm start # Start production server

CLI

npm run cli # Run CLI commands

Database

npm run db:migrate # Run migrations (planned)
npm run db:seed # Seed database (planned)

Testing

npm test # Run tests (planned)
npm run test:watch # Watch mode (planned)
npm run test:coverage # Coverage report (planned)

Linting

npm run lint # ESLint
npm run lint:fix # Auto-fix issues
npm run format # Prettier (planned)

Docker

npm run docker:build # Build Docker image
npm run docker:up # Start containers
npm run docker:down # Stop containers
npm run docker:logs # View logs
`

$3

- Language: TypeScript (strict mode)
- Formatting: Prettier (2 spaces, single quotes)
- Linting: ESLint (Airbnb config)
- Naming:
- Files: kebab-case.ts
- Classes: PascalCase
- Functions: camelCase
- Constants: UPPER_SNAKE_CASE
- Interfaces: PascalCase (no I prefix)

$3

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature`)
5. Open Pull Request

PR Requirements:
- Clear description of changes
- Tests for new features (when test framework is ready)
- No linting errors
- Updated documentation if needed

---

🗺️ Roadmap

$3

- [x] ✅ Core code indexing (AST + dependency graph)
- [x] ✅ Semantic memory (Qdrant + embeddings)
- [x] ✅ Impact analysis engine
- [x] ✅ Web dashboard
- [x] ✅ Authentication (Email, OAuth, Device Flow)
- [x] ✅ Email verification system
- [x] ✅ Disposable email protection
- [x] ✅ PostgreSQL integration
- [x] ✅ Redis caching
- [x] ✅ Audit logging
- [x] ✅ Admin panel
- [x] ✅ Domain & SSL setup
- [ ] ⏳ Payment integration (Revolut)
- [ ] ⏳ Unit & integration tests

$3

- [ ] GitHub PR analysis (automatic comments)
- [ ] GitLab integration
- [ ] VS Code extension
- [ ] Slack/Discord notifications
- [ ] Custom architecture rules engine
- [ ] Team collaboration features
- [ ] Advanced metrics dashboard
- [ ] Code quality trends

$3

- [ ] JetBrains IDE plugin (IntelliJ, WebStorm)
- [ ] Automated refactoring suggestions with code generation
- [ ] Technical debt tracking & prioritization
- [ ] AI-powered architecture recommendations
- [ ] On-premise deployment option
- [ ] SAML/SSO authentication

$3

- [ ] Real-time collaboration (shared analysis sessions)
- [ ] Custom LLM fine-tuning for domain-specific code
- [ ] Advanced visualization (3D dependency graphs)
- [ ] Mobile app (iOS/Android)
- [ ] Kubernetes operator
- [ ] Multi-region deployment

$3

- AI Pair Programmer: Real-time coding assistant with full codebase context
- Autonomous Refactoring: AI automatically refactors technical debt
- Predictive Analytics: Predict bugs before they happen
- Architecture Governance: Enforce architectural rules at commit time
- Cross-Project Intelligence: Learn from multiple projects to improve recommendations

---

📄 License

MIT License

Copyright (c) 2026 ArchiCore

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

📚 Documentation

- Complete API & CLI Reference - Все endpoints, команды и языки
- Online Documentation - Интерактивная документация
- TODO & Roadmap - Планы развития
- Business Model - Бизнес-модель

🤝 Support

- Email: support@archicore.io
- GitHub Issues: https://github.com/yourusername/archicore/issues
- Twitter: @archicore_ai
- Discord: https://discord.gg/archicore (coming soon)

---

🙏 Acknowledgments

- Tree-sitter - Parsing framework
- Qdrant - Vector database
- Anthropic - Claude AI
- Jina AI - Code embeddings
- PostgreSQL - Reliable database
- Redis - Fast caching
- Express.js - Web framework
- Docker - Containerization
- All contributors who helped make ArchiCore better!

---