База даних

AgentCore використовує PostgreSQL 16 із розширенням pgvector для пошуку за векторною схожістю. Схемою керує Prisma 6, файл — prisma/schema.prisma.

Налаштування

# Start PostgreSQL
docker compose up -d postgres

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma migrate dev

# Visual database browser
npm run db:studio

Огляд моделей

Схема містить 26 моделей, згрупованих по доменах.

RBAC і організація

Модель	Призначення	Ключові поля
SystemRole	Кастомні та вбудовані RBAC-ролі	name, slug, isSystem, allDepartments, departmentIds, permissions
Department	Межа tenant/відділу для більшості даних	name, slug, color, description, settings, isArchived
User	Автентифіковані користувачі та HR-стан	email, name, phone, passwordHash, legacy role, roleId, departmentId, avatarUrl, tokenVersion, permission- і department-override
PasswordResetToken	Процес password reset	userId, token, expiresAt, usedAt

User.role тримає legacy-enum (admin, approver, dept_head, employee) для сумісності. Поточна авторизація використовує SystemRole плюс per-user extraPermissions, revokedPermissions, extraDepartmentIds і revokedDepartmentIds.

База знань

Модель	Призначення	Ключові поля
KnowledgeBase	Пул документів відділу	departmentId, name, description, config
Document	Вихідний документ або згенерований вихідний файл	knowledgeBaseId, title, type, originalUrl, status, metadata
Chunk	Пошуковий фрагмент тексту	documentId, content, embedding, syntheticQuestions, metadata
ChunkQuestion	Шлях пошуку за синтетичними Q&A	chunkId, question, embedding

Chunk.embedding і ChunkQuestion.embedding — це колонки vector(1536) і мають відповідати розмірності обраної embedding-моделі.

Розмови та простори імен

Модель	Призначення	Ключові поля
Namespace	Кастомна конфігурація асистента для відділу	name, departmentId, systemPrompt, persona, config
NamespacePlugin	Увімкнені integration-плагіни per-namespace	namespaceId, pluginId, config, enabled
Conversation	Conversation thread користувача	userId, channel, status, metadata, namespaceId
Message	Повідомлення розмови	conversationId, role, content, sources
PiiRedactionMap	Зворотні PII-плейсхолдери для розмов	conversationId, placeholder, entityType, encryptedValue

Простори імен обгортають персоналізацію, матрицю довіри, конфігурацію адаптера, плагіни, розмови, шаблони документів та agent tasks.

Схвалення та наміри

Модель	Призначення	Ключові поля
Approval	HITL-воркфлоу схвалення	messageId, approverId, status, editedContent, approverNotes, escalatedToId, escalationReason, intentName
IntentTrust	Матриця довіри для автономних відправлень	namespaceId, intentName, successfulCount, threshold, isAutonomous, samplingRate
IntentExample	Мічені фрази для vector intent classification	namespaceId, intentName, phrase, embedding, metadata

Генерація документів

Модель	Призначення	Ключові поля
Template	Legacy file-based шаблони	name, departmentId, filePath, variables
DocumentTemplate	API-керовані Handlebars-шаблони	namespaceId, departmentId, name, description, category, templateBody, variables, outputFormat, createdBy
DocumentGeneration	Історія рендерів та згенеровані виходи	templateId, userId, input, output, outputFileId, status, error

Згенеровані файли можуть бути збережені назад як Document через outputFileId, що дозволяє generated-документам брати участь у стандартних knowledge-base воркфлоу.

Employee memory та agent execution

Модель	Призначення	Ключові поля
EmployeeProfile	Екстрагована памʼять/профіль користувача	userId, summary, currentProjects, preferences, frequentIntents, accessLevel, profileVersion, lastExtractedAt
AgentTask	Запис про виконання agent runner-задачі	namespaceId, conversationId, messageId, adapterType, status, token/cost/duration поля, metadata, таймстампи
AgentToolCall	Step-level трейс виконання агента	agentTaskId, stepName, status, inputData, outputData, durationMs, errorMessage

Observability та сповіщення

Модель	Призначення	Ключові поля
AuditLog	Бізнес- та security-audit trail	userId, action, entityType, entityId, changes, ipAddress, userAgent
AgentRun	Summary-запис Langfuse/OpenAI-трейса	traceId, conversationId, provider, model, token/cost/latency поля, status
RetrievalHit	RAG-retrieval evidence для трейса	agentRunId, chunkId, documentId, rank, score, rerankScore
Notification	Центр сповіщень користувача	userId, type, title, body, entityType, entityId, readAt

Enum-и

Role:                admin | approver | dept_head | employee
DocumentType:        pdf | docx | txt | url | image
DocumentStatus:      pending | processing | ready | failed
ConversationChannel: web | whatsapp | telegram | slack | email
ConversationStatus:  active | closed | escalated | awaiting_approval
MessageRole:         user | assistant | system
ApprovalStatus:      pending | approved | rejected | edited | escalated
AgentTaskStatus:     queued | running | done | failed | timeout

Операційні нотатки

• Ізоляція відділу йде напряму через departmentId або через повʼязані записи Namespace, User чи KnowledgeBase.
• Soft-deactivation використовується для користувачів (isActive = false) і відділів (isArchived = true).
• JWT-інвалідація використовує User.tokenVersion; password reset, logout-all, transfer департаменту та деактивація його інкрементують.
• Document uploads і згенеровані document outputs обидва використовують Document, але згенеровані виходи мають metadata.source = "document_generation".

Міграції

Міграції лежать у prisma/migrations/.

npx prisma migrate dev --name <migration_name>

Для продакшн-деплою:

npx prisma migrate deploy