> ## Documentation Index
> Fetch the complete documentation index at: https://docs.junis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understanding the Junis platform architecture and key concepts

## What is the Junis platform architecture?

Junis is an AI workforce platform built on a **multi-agent architecture**: every organization runs its own orchestrator that routes requests to specialized agents, which use tools, MCP integrations, RAG knowledge bases, and persistent memory to complete tasks. This page explains the core concepts behind that architecture — agents, organizations, sessions, tools, and the systems that connect them.

***

## 1. Agents

**Agents** are the fundamental building blocks of Junis. Think of them as AI workers with specific skills and responsibilities.

### Agent Types

<CardGroup cols={2}>
  <Card title="LLM Agent" icon="brain">
    Individual AI worker that processes tasks using a language model

    * Has its own instructions and tools
    * Can call sub-agents
    * Specialized for specific tasks
  </Card>

  <Card title="Sequential Agent" icon="arrow-right">
    Executes sub-agents one after another in order

    * Step-by-step processing
    * Output of one becomes input of next
    * Perfect for pipelines
  </Card>

  <Card title="Parallel Agent" icon="code-branch">
    Runs multiple sub-agents simultaneously

    * Concurrent execution
    * Aggregates results
    * Faster for independent tasks
  </Card>

  <Card title="Loop Agent" icon="rotate">
    Repeats sub-agents until a condition is met

    * Iterative processing
    * Configurable max iterations
    * Useful for retry logic
  </Card>
</CardGroup>

### Agent Hierarchy

```mermaid theme={null}
graph TD
    Orchestrator[Orchestrator<br/>Entry point for all requests]

    Orchestrator -->|Routes to| Sequential[Sequential Agent<br/>Data Pipeline]
    Orchestrator -->|Routes to| Parallel[Parallel Agent<br/>Multi-task]

    Sequential --> Agent1[LLM Agent 1<br/>Data Collection]
    Sequential --> Agent2[LLM Agent 2<br/>Data Analysis]
    Sequential --> Agent3[LLM Agent 3<br/>Report Generation]

    Parallel --> Agent4[LLM Agent 4<br/>Task A]
    Parallel --> Agent5[LLM Agent 5<br/>Task B]
    Parallel --> Agent6[LLM Agent 6<br/>Task C]
```

<Note>
  **Orchestrator** is a special agent that serves as the entry point for all requests. It routes messages to appropriate sub-agents based on the user's intent.
</Note>

***

## 2. Multi-Tenant System

Junis is a **multi-tenant platform** where each organization has isolated data and configurations.

### Organization Isolation

```mermaid theme={null}
graph LR
    System[Junis Platform]

    System --> Org1[Organization A]
    System --> Org2[Organization B]
    System --> Org3[Organization C]

    Org1 --> A1[Agents]
    Org1 --> A2[Sessions]
    Org1 --> A3[RAG Data]

    Org2 --> B1[Agents]
    Org2 --> B2[Sessions]
    Org2 --> B3[RAG Data]
```

**Key Points**:

* Each organization has its own **Orchestrator**
* Agents are **scoped to organizations**
* Sessions and data are **completely isolated**
* Users can belong to multiple organizations

### Organization Roles

| Role       | Permissions                                       |
| ---------- | ------------------------------------------------- |
| **OWNER**  | Full organization control, manage all settings    |
| **ADMIN**  | Manage agents, tools, schedules, members          |
| **MEMBER** | Use agents, create sessions, upload RAG documents |

<Note>
  Platform-level roles (SUPER\_ADMIN, SUPPORT) are managed separately for system administration purposes.
</Note>

***

## 3. Sessions

A **session** represents a conversation between a user and the Junis system. Sessions maintain context across multiple messages.

### Session Lifecycle

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database

    User->>Frontend: Send first message
    Frontend->>API: POST /chat (no session_id)
    API->>Database: Create new session
    Database-->>API: Return session_id
    API-->>Frontend: Stream response + session_id
    Frontend->>Frontend: Store session_id

    User->>Frontend: Send follow-up message
    Frontend->>API: POST /chat (with session_id)
    API->>Database: Load session context
    API-->>Frontend: Stream response with context
```

**Session Properties**:

* **Persistent**: Stored in PostgreSQL database
* **Contextual**: Agents remember previous messages
* **Searchable**: Full conversation history available via API
* **Resumable**: Can continue sessions across disconnections

***

## 4. Tools

**Tools** are functions that agents can call to perform actions or retrieve information.

### Tool Categories

<Tabs>
  <Tab title="Built-in Tools">
    **Python Functions** registered in the system:

    * `various_of_tools`: Useful Tools
  </Tab>

  <Tab title="MCP Tools">
    **External services** via Model Context Protocol:

    * **GitHub**: `create_repository`, `create_issue`, `list_commits`
    * **Firecrawl**: `scrape_url`, `crawl_website`, `map_website`
    * **Remote MCPs**: `-`
    * **Local MCPs**: `-`
      Dynamic toolsets from MCP servers
  </Tab>

  <Tab title="RAG Tools">
    **Document search** tools powered by Vertex AI:

    * Auto-generated per knowledge base
    * Semantic search across uploaded documents
    * Returns relevant excerpts with citations
    * Fully managed by the system
  </Tab>
</Tabs>

### Tool Calling Flow

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Google ADK
    participant Tool
    participant External Service

    Agent->>Google ADK: Generate response
    Google ADK->>Google ADK: Detect tool call needed
    Google ADK->>Tool: Call tool with parameters
    Tool->>External Service: Execute action
    External Service-->>Tool: Return result
    Tool-->>Google ADK: Return formatted result
    Google ADK-->>Agent: Continue with result
```

***

## 5. Model Context Protocol (MCP)

**MCP** is a standard protocol for connecting AI agents to external services. Junis supports both **Remote** and **Local** MCP servers.

### MCP Architecture

```mermaid theme={null}
graph TB
    Agent[LLM Agent]
    Loader[Dynamic Agent Loader]
    Integration[MCP Integration Layer]

    Agent -->|Load MCP| Loader
    Loader -->|Initialize| Integration

    Integration -->|HTTP/SSE| Remote[Remote MCP Server]
    Integration -->|Subprocess| Custom[Custom MCP Server]

    Remote --> GitHub[GitHub API]
    Remote --> Firecrawl[Firecrawl API]

    subgraph "Remote MCP"
        Remote
        GitHub
        Firecrawl
    end

    subgraph "Custom MCP"
        Custom
    end
```

### Authentication Hierarchy

MCP credentials support **multi-level authentication**. Users can configure credentials at different levels, with automatic fallback to appropriate defaults.

<Note>
  For detailed authentication configuration, including priority systems and credential management, refer to the MCP Integration Guide in the Admin documentation.
</Note>

***

## 6. RAG (Retrieval-Augmented Generation)

**RAG** enhances agents with knowledge from your documents. When a user asks a question, the system:

1. **Searches** relevant documents using semantic search
2. **Retrieves** the most relevant excerpts
3. **Augments** the agent's prompt with this context
4. **Generates** a response informed by your documents

### RAG Workflow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Agent
    participant RAG Tool
    participant Vertex AI Search
    participant GCS

    User->>Agent: Ask question
    Agent->>Agent: Detect need for knowledge
    Agent->>RAG Tool: Call rag_datastore_id()
    RAG Tool->>Vertex AI Search: Semantic search
    Vertex AI Search->>GCS: Fetch document chunks
    GCS-->>Vertex AI Search: Return chunks
    Vertex AI Search-->>RAG Tool: Return relevant excerpts
    RAG Tool-->>Agent: Formatted context
    Agent-->>User: Answer with citations
```

### DataStore Structure

```
Organization: Acme Corp
├── DataStore: salesforce_brands
│   ├── brands_2026_q1.pdf
│   ├── brands_2026_q2.pdf
│   └── brands_pricing.xlsx
├── DataStore: marketing_assets
│   ├── campaign_brief.docx
│   └── creative_guidelines.pdf
└── DataStore: product_docs
    ├── api_reference.md
    └── user_manual.pdf
```

***

## 7. Memory System

**Memory** gives your AI agents the ability to remember users across conversations, building a personalized understanding over time.

### Memory Tiers

```mermaid theme={null}
graph LR
    Chat[Conversations] -->|After each session| D1[Daily Memory]
    D1 -->|Monthly| D30[Monthly Summary]
    D30 -->|Quarterly| D90[Quarterly Summary]
    D90 -->|Yearly| D365[Yearly Narrative]
    Chat -->|Key facts| D0[Eternal Memory]
    User[User Profile] -.->|Editable| Agent[Agent Context]
    D0 -.-> Agent
    D1 -.-> Agent
    D30 -.-> Agent
```

| Tier                         | What It Stores                            | How It's Updated              |
| ---------------------------- | ----------------------------------------- | ----------------------------- |
| **User Profile**             | Name, role, preferences, expertise        | Agent or user updates anytime |
| **Eternal Memory**           | Permanent facts and standing instructions | Agent stores on user request  |
| **Daily Memory**             | Conversation summaries                    | Automatic after each session  |
| **Monthly/Quarterly/Yearly** | Consolidated patterns and narratives      | AI-powered auto-consolidation |

**Key Properties**:

* **Automatic**: Memory is collected and consolidated without manual action
* **Per-User**: Each user has isolated memory — no cross-user visibility
* **Contextual Injection**: Agents automatically load relevant memories at the start of each conversation
* **AI Consolidation**: Memories are periodically reviewed and summarized, mimicking human memory

<Note>
  For details on managing memory and available tools, see the [Memory System Guide](/guides/memory-system).
</Note>

***

## 8. Soul & Identity

**Soul & Identity** defines your AI team's personality at the organization level. It controls how agents think and communicate.

### Two Files

<CardGroup cols={2}>
  <Card title="soul.md" icon="brain">
    **Philosophy & Thinking** — Core values, decision-making principles, reasoning style
  </Card>

  <Card title="identity.md" icon="user">
    **Expression & Persona** — Communication tone, language patterns, personality traits
  </Card>
</CardGroup>

### How It Works

```mermaid theme={null}
graph TD
    Soul[soul.md] --> Inject[Auto-Injection]
    Identity[identity.md] --> Inject
    Inject --> Every[Every Agent Conversation]
```

* **Organization-scoped**: All agents inherit the same personality
* **Automatic injection**: Loaded into every conversation without manual configuration
* **Admin-only editing**: Only Admin/Owner roles can modify
* **Instant effect**: Changes apply to the next conversation

<Note>
  Soul & Identity defines *who* your AI is. Agent instructions define *what* each agent does. See the [Soul & Identity Guide](/guides/soul-identity).
</Note>

***

## 9. Streaming

Junis supports **real-time streaming** for better user experience.

### Streaming Modes

<CardGroup cols={2}>
  <Card title="Server-Sent Events (SSE)" icon="bolt">
    **REST API streaming** via `/api/external/v1/chat/completions`

    * HTTP with `stream: true`
    * OpenAI-compatible format
    * Token-by-token delivery
  </Card>

  <Card title="WebSocket" icon="plug">
    **Persistent connection** via `/ws/chat`

    * Bidirectional communication
    * Pipeline events
    * File uploads
    * Payment flows
  </Card>
</CardGroup>

### Event Types (WebSocket)

| Event Type        | Description              | Example                                             |
| ----------------- | ------------------------ | --------------------------------------------------- |
| `stream_token`    | Individual text token    | `{"type": "stream_token", "token": "Hello"}`        |
| `agent_routing`   | Agent handoff            | `{"type": "agent_routing", "from": "A", "to": "B"}` |
| `agent_started`   | Agent begins processing  | `{"type": "agent_started", "agent": "Analyzer"}`    |
| `agent_completed` | Agent finishes           | `{"type": "agent_completed", "duration_ms": 1234}`  |
| `stream_complete` | Entire response complete | `{"type": "stream_complete"}`                       |

***

## 10. Performance Optimization

Junis uses **intelligent caching and optimization** to ensure fast, responsive agent interactions.

### Caching System

The platform implements a multi-tier caching strategy:

* **Agent Configuration**: Automatically cached for rapid access
* **Session Context**: Persisted for conversation continuity
* **External Integrations**: Connection pooling and result caching
* **Database Queries**: Query-result caching layer

### Cache Invalidation

Caches are automatically updated when:

* Agent configuration changes (Admin UI)
* Agent relationships modified (Admin UI)
* Organization settings updated
* External service credentials change

<Note>
  For detailed information about caching strategy, performance tuning, and optimization techniques, refer to the Operations Guide in the Admin documentation.
</Note>

***

## 11. Scheduled Tasks

**Scheduled Tasks** enable automation by running agents at specific times or intervals.

### Schedule Types

<CardGroup cols={3}>
  <Card title="ONCE" icon="calendar">
    Run at a specific date/time
  </Card>

  <Card title="EVERY_MINUTES" icon="clock">
    Repeat every N minutes
  </Card>

  <Card title="EVERY_HOURS" icon="clock">
    Repeat every N hours
  </Card>

  <Card title="DAILY" icon="calendar-day">
    Repeat every day at specified hour
  </Card>

  <Card title="WEEKLY" icon="calendar-week">
    Run on specific weekdays
  </Card>

  <Card title="MONTHLY" icon="calendar">
    Execute monthly on specific day
  </Card>
</CardGroup>

### Schedule Execution

```mermaid theme={null}
sequenceDiagram
    participant Celery Beat
    participant Celery Worker
    participant Orchestrator
    participant Database

    Celery Beat->>Celery Beat: Check due tasks
    Celery Beat->>Celery Worker: Trigger task
    Celery Worker->>Database: Load task config
    Celery Worker->>Orchestrator: Send prompt
    Orchestrator-->>Celery Worker: Response
    Celery Worker->>Database: Save result
```

**Key Features**:

* Timezone-aware scheduling
* Session reuse or new session per run
* Execution history and logs
* Enable/disable without deletion

***

## Next Steps

Now that you understand the core concepts, explore these guides:

<CardGroup cols={2}>
  <Card title="Agent System Overview" icon="diagram-project" href="/getting-started/agent-system">
    Learn how to combine agent types
  </Card>

  <Card title="Junis Magic" icon="wand-magic-sparkles" href="/guides/junis-magic">
    Manage your platform from Claude Desktop
  </Card>

  <Card title="Memory System" icon="brain" href="/guides/memory-system">
    Persistent AI memory across conversations
  </Card>

  <Card title="Soul & Identity" icon="sparkles" href="/guides/soul-identity">
    Define your AI team's personality
  </Card>

  <Card title="Integrate External Services" icon="plug" href="/guides/mcp/overview">
    Connect MCP and Composio platforms
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/authentication">
    Integrate programmatically
  </Card>
</CardGroup>