# arthur-ficial/apfel architecture

> Architecture diagram of the GitHub repository arthur-ficial/apfel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arthur-ficial/apfel
- Repository: https://github.com/arthur-ficial/apfel

## Overview

apfel is a macOS command-line interface and local OpenAI-compatible server for Apple’s on-device FoundationModels. The main workflow accepts a prompt, piped input, or attachments; prepares conversation context; runs model generation and optional MCP tool rounds; then returns text or structured output. The server exposes compatible HTTP APIs, including chat and Responses-style handling. The README documents additional schema-constrained output, token counting, vision inputs, demos, and MCP integrations. Some implementation files were not sampled, so uncertain wiring is omitted or marked unverified.

Main entry points: [`Sources/main.swift`](https://github.com/arthur-ficial/apfel/blob/main/Sources/main.swift) (CLI dispatch), [`Sources/Server.swift`](https://github.com/arthur-ficial/apfel/blob/main/Sources/Server.swift) (HTTP server), [`Sources/ContextManager.swift`](https://github.com/arthur-ficial/apfel/blob/main/Sources/ContextManager.swift) (Context assembly), [`Sources/Session.swift`](https://github.com/arthur-ficial/apfel/blob/main/Sources/Session.swift) (Model session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and interaction"]
  node_cli["CLI dispatch<br/>[main.swift]"]
  node_arguments["Argument parsing<br/>[CLIArguments.swift]"]
  node_chat["Interactive chat<br/>[ChatHistory.swift]"]
  node_output["Output formatting<br/>[Output.swift]"]
  node_files["File input"]
  node_demos["Bundled demos"]
end

subgraph group_api["HTTP API"]
  node_server["HTTP server<br/>[Server.swift]"]
  node_chatapi["Chat completions<br/>[Handlers.swift]"]
  node_responses["Responses API"]
  node_security["Server security"]
end

subgraph group_inference["Model and context"]
  node_context["Context assembly"]
  node_session["Model session<br/>[Session.swift]"]
  node_tokens["Token counting<br/>[TokenCounter.swift]"]
  node_contextpolicy["Context strategy"]
  node_schemas["Schema conversion"]
  node_schemainput["Schema parsing<br/>[SchemaParser.swift]"]
  node_vision["Image input<br/>[ImageInput.swift]"]
end

subgraph group_tools["Tools and integrations"]
  node_mcpclient["MCP client<br/>[MCPClient.swift]"]
  node_mcpdispatch["Tool execution"]
  node_exchange["Tool exchange grouping"]
  node_directive["Tool directives"]
end

node_user(("CLI user"))
node_httpclient(("API client"))
node_foundation{{"FoundationModels"}}
node_mcpservers{{"MCP servers"}}

node_user -->|"invokes"| node_cli
node_cli -->|"parses arguments"| node_arguments
node_cli -->|"reads attachments"| node_files
node_cli -->|"starts server"| node_server
node_cli -.->|"prints results"| node_output
node_user -->|"starts chat"| node_chat
node_chat -.->|"runs conversation"| node_session
node_httpclient -->|"sends requests"| node_server
node_server -.->|"routes chat requests"| node_chatapi
node_server -.->|"routes Responses requests"| node_responses
node_server -->|"uses security checks"| node_security
node_chatapi -->|"builds session context"| node_context
node_responses -->|"builds session context"| node_context
node_context -->|"converts tool schemas"| node_schemas
node_context -.->|"prepares session"| node_session
node_session -->|"counts context"| node_tokens
node_session -->|"executes tool calls"| node_mcpdispatch
node_mcpdispatch -.->|"dispatches MCP calls"| node_mcpclient
node_mcpclient -->|"communicates with"| node_mcpservers
node_context -->|"uses grouped history"| node_exchange
node_chatapi -->|"applies tool directives"| node_directive
node_responses -->|"applies tool directives"| node_directive
node_arguments -->|"selects strategy"| node_contextpolicy
node_arguments -->|"parses schema"| node_schemainput
node_schemainput -.->|"provides schema definitions"| node_schemas
node_session -->|"generates responses"| node_foundation
node_tokens -->|"counts tokens"| node_foundation
node_cli -->|"writes bundled demos"| node_demos
node_files -.->|"supports image attachments"| node_vision

click node_cli "https://github.com/arthur-ficial/apfel/blob/main/Sources/main.swift"
click node_arguments "https://github.com/arthur-ficial/apfel/blob/main/Sources/CLI/CLIArguments.swift"
click node_chat "https://github.com/arthur-ficial/apfel/blob/main/Sources/CLI/ChatHistory.swift"
click node_output "https://github.com/arthur-ficial/apfel/blob/main/Sources/Output.swift"
click node_files "https://github.com/arthur-ficial/apfel/blob/main/Sources/LesbarFileReader.swift"
click node_server "https://github.com/arthur-ficial/apfel/blob/main/Sources/Server.swift"
click node_chatapi "https://github.com/arthur-ficial/apfel/blob/main/Sources/Handlers.swift"
click node_responses "https://github.com/arthur-ficial/apfel/blob/main/Sources/ResponsesHandlers.swift"
click node_security "https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ServerSecurity.swift"
click node_context "https://github.com/arthur-ficial/apfel/blob/main/Sources/ContextManager.swift"
click node_session "https://github.com/arthur-ficial/apfel/blob/main/Sources/Session.swift"
click node_tokens "https://github.com/arthur-ficial/apfel/blob/main/Sources/TokenCounter.swift"
click node_contextpolicy "https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ContextStrategy.swift"
click node_schemas "https://github.com/arthur-ficial/apfel/blob/main/Sources/SchemaConverter.swift"
click node_schemainput "https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/SchemaParser.swift"
click node_mcpclient "https://github.com/arthur-ficial/apfel/blob/main/Sources/MCPClient.swift"
click node_mcpdispatch "https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ToolCallHandler.swift"
click node_exchange "https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ToolExchangeGrouping.swift"
click node_directive "https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ToolCallingDirective.swift"
click node_demos "https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/GeneratedDemos.swift"
click node_vision "https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ImageInput.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_arguments,node_chat,node_output,node_files,node_demos,node_user,node_httpclient toneBlue
class node_server,node_chatapi,node_responses,node_security toneAmber
class node_context,node_session,node_tokens,node_contextpolicy,node_schemas,node_schemainput,node_vision,node_mcpservers toneMint
class node_mcpclient,node_mcpdispatch,node_exchange,node_directive toneRose
class node_foundation toneIndigo
```

## Components

### CLI and interaction

- [CLI dispatch](https://github.com/arthur-ficial/apfel/blob/main/Sources/main.swift): `Sources/main.swift`
- [Argument parsing](https://github.com/arthur-ficial/apfel/blob/main/Sources/CLI/CLIArguments.swift): `Sources/CLI/CLIArguments.swift`
- [Interactive chat](https://github.com/arthur-ficial/apfel/blob/main/Sources/CLI/ChatHistory.swift): `Sources/CLI/ChatHistory.swift`
- [Output formatting](https://github.com/arthur-ficial/apfel/blob/main/Sources/Output.swift): `Sources/Output.swift`
- [File input](https://github.com/arthur-ficial/apfel/blob/main/Sources/LesbarFileReader.swift): `Sources/LesbarFileReader.swift`
- [Bundled demos](https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/GeneratedDemos.swift): `Sources/Core/GeneratedDemos.swift`

### HTTP API

- [HTTP server](https://github.com/arthur-ficial/apfel/blob/main/Sources/Server.swift): `Sources/Server.swift`
- [Chat completions](https://github.com/arthur-ficial/apfel/blob/main/Sources/Handlers.swift): `Sources/Handlers.swift`
- [Responses API](https://github.com/arthur-ficial/apfel/blob/main/Sources/ResponsesHandlers.swift): `Sources/ResponsesHandlers.swift`
- [Server security](https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ServerSecurity.swift): `Sources/Core/ServerSecurity.swift`

### Model and context

- [Context assembly](https://github.com/arthur-ficial/apfel/blob/main/Sources/ContextManager.swift): `Sources/ContextManager.swift`
- [Model session](https://github.com/arthur-ficial/apfel/blob/main/Sources/Session.swift): `Sources/Session.swift`
- [Token counting](https://github.com/arthur-ficial/apfel/blob/main/Sources/TokenCounter.swift): `Sources/TokenCounter.swift`
- [Context strategy](https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ContextStrategy.swift): `Sources/Core/ContextStrategy.swift`
- [Schema conversion](https://github.com/arthur-ficial/apfel/blob/main/Sources/SchemaConverter.swift): `Sources/SchemaConverter.swift`
- [Schema parsing](https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/SchemaParser.swift): `Sources/Core/SchemaParser.swift`
- [Image input](https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ImageInput.swift): `Sources/Core/ImageInput.swift`

### Tools and integrations

- [MCP client](https://github.com/arthur-ficial/apfel/blob/main/Sources/MCPClient.swift): `Sources/MCPClient.swift`
- [Tool execution](https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ToolCallHandler.swift): `Sources/Core/ToolCallHandler.swift`
- [Tool exchange grouping](https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ToolExchangeGrouping.swift): `Sources/Core/ToolExchangeGrouping.swift`
- [Tool directives](https://github.com/arthur-ficial/apfel/blob/main/Sources/Core/ToolCallingDirective.swift): `Sources/Core/ToolCallingDirective.swift`

### Other components

- **CLI user**
- **API client**
- **FoundationModels**
- **MCP servers**

## Connections

- CLI user → CLI dispatch: invokes (evidence: `README.md`)
- CLI dispatch → Argument parsing: parses arguments (evidence: `Sources/main.swift`)
- CLI dispatch → File input: reads attachments (evidence: `Sources/main.swift`)
- CLI dispatch → HTTP server: starts server (evidence: `Sources/main.swift`)
- CLI dispatch → Output formatting: prints results
- CLI user → Interactive chat: starts chat (evidence: `README.md`)
- Interactive chat → Model session: runs conversation
- API client → HTTP server: sends requests (evidence: `README.md`)
- HTTP server → Chat completions: routes chat requests
- HTTP server → Responses API: routes Responses requests
- HTTP server → Server security: uses security checks (evidence: `Sources/Server.swift`)
- Chat completions → Context assembly: builds session context (evidence: `Sources/Handlers.swift`)
- Responses API → Context assembly: builds session context (evidence: `Sources/ResponsesHandlers.swift`)
- Context assembly → Schema conversion: converts tool schemas (evidence: `Sources/ContextManager.swift`)
- Context assembly → Model session: prepares session (evidence: `Sources/Session.swift`)
- Model session → Token counting: counts context (evidence: `Sources/Session.swift`)
- Model session → Tool execution: executes tool calls (evidence: `Sources/Session.swift`)
- Tool execution → MCP client: dispatches MCP calls
- MCP client → MCP servers: communicates with (evidence: `README.md`)
- Context assembly → Tool exchange grouping: uses grouped history (evidence: `Sources/ContextManager.swift`)
- Chat completions → Tool directives: applies tool directives (evidence: `Sources/Handlers.swift`)
- Responses API → Tool directives: applies tool directives (evidence: `Sources/ResponsesHandlers.swift`)
- Argument parsing → Context strategy: selects strategy (evidence: `Sources/CLI/CLIArguments.swift`)
- Argument parsing → Schema parsing: parses schema (evidence: `Sources/CLI/CLIArguments.swift`)
- Schema parsing → Schema conversion: provides schema definitions (evidence: `Sources/SchemaConverter.swift`)
- Model session → FoundationModels: generates responses (evidence: `README.md`)
- Token counting → FoundationModels: counts tokens (evidence: `Sources/TokenCounter.swift`)
- CLI dispatch → Bundled demos: writes bundled demos (evidence: `README.md`)
- File input → Image input: supports image attachments