# cs80-team/goolean architecture

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

- Interactive diagram: https://gitdiagram.com/cs80-team/goolean
- Repository: https://github.com/cs80-team/goolean

## Overview

Goolean is a boolean-model document search engine exposed through an interactive shell or gRPC services. Its main workflow loads or uploads documents, tokenizes and processes their text, builds an inverted index, and evaluates AND/OR/NOT queries to return matching documents. The README also describes listing, finding, and opening indexed files. The graph combines documented capabilities with visible calls; loader and some processing internals are represented at their source paths, but unsampled implementation details and connections are not inferred.

Main entry points: [`internal/engine/engine.go`](https://github.com/cs80-team/goolean/blob/master/internal/engine/engine.go) (Search engine), [`main.go`](https://github.com/cs80-team/goolean/blob/master/main.go) (Application startup), [`internal/service/file.go`](https://github.com/cs80-team/goolean/blob/master/internal/service/file.go) (File service), [`internal/service/query.go`](https://github.com/cs80-team/goolean/blob/master/internal/service/query.go) (Query service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_main["Application startup<br/>[main.go]"]
end

subgraph group_ingest["Document ingestion"]
  node_loader["Document loader<br/>[loader.go]"]
  node_indexer["Document indexer<br/>[indexer.go]"]
  node_tokenizer["Tokenizer<br/>[tokenizer.go]"]
  node_text_processing["Text processing<br/>[textprocessing.go]"]
end

subgraph group_search["Search engine"]
  node_engine["Search engine<br/>[engine.go]"]
  node_query_eval["Boolean query evaluation<br/>[query.go]"]
  node_index_manager[("Inverted index<br/>[index_manager.go]")]
  node_structures_factory["Index structures factory"]
  node_skip_list_factory["Skip-list factory"]
  node_ordered_structures["Ordered index structures"]
  node_document_store[("Indexed documents<br/>[document.go]")]
end

subgraph group_interfaces["User interfaces"]
  node_commands["Shell commands<br/>[engine_commands.go]"]
  node_query_service["Query service<br/>[query.go]"]
  node_file_service["File service<br/>[file.go]"]
  node_uploaded_files[("Uploaded files")]
  node_query_transport["Query gRPC API"]
  node_file_transport["File gRPC API"]
  node_document_mapper["Document mapper<br/>[document_mapper.go]"]
end

node_shell_user(("Shell user"))
node_grpc_client(("gRPC client"))
node_filesystem[("Local filesystem")]

node_shell_user -->|"starts shell"| node_main
node_main -->|"configures"| node_engine
node_main -->|"starts shell"| node_commands
node_main -->|"creates"| node_query_service
node_main -->|"creates"| node_file_service
node_grpc_client -->|"sends queries"| node_query_transport
node_grpc_client -->|"manages files"| node_file_transport
node_query_transport -->|"routes requests"| node_query_service
node_file_transport -->|"routes requests"| node_file_service
node_commands -->|"queries"| node_engine
node_commands -->|"loads documents"| node_engine
node_query_service -->|"evaluates query"| node_engine
node_query_service -->|"maps results"| node_document_mapper
node_document_mapper -->|"creates response documents"| node_query_transport
node_file_service -->|"indexes upload"| node_engine
node_file_service -->|"writes and reads"| node_filesystem
node_engine -->|"keeps documents"| node_document_store
node_engine -.->|"indexes text"| node_indexer
node_engine -.->|"loads corpus"| node_loader
node_engine -->|"configures tokenization"| node_tokenizer
node_engine -->|"configures processing"| node_text_processing
node_indexer -->|"tokenizes documents"| node_tokenizer
node_engine -->|"evaluates queries"| node_query_eval
node_query_eval -->|"reads postings"| node_index_manager
node_engine -->|"manages postings"| node_index_manager
node_index_manager -->|"creates structures"| node_structures_factory
node_skip_list_factory -->|"creates skip lists"| node_ordered_structures
node_structures_factory -.->|"builds index structures"| node_ordered_structures
node_main -->|"selects implementation"| node_skip_list_factory
node_file_service -->|"receives uploads"| node_uploaded_files

click node_main "https://github.com/cs80-team/goolean/blob/master/main.go"
click node_commands "https://github.com/cs80-team/goolean/blob/master/engine_commands.go"
click node_query_service "https://github.com/cs80-team/goolean/blob/master/internal/service/query.go"
click node_file_service "https://github.com/cs80-team/goolean/blob/master/internal/service/file.go"
click node_engine "https://github.com/cs80-team/goolean/blob/master/internal/engine/engine.go"
click node_loader "https://github.com/cs80-team/goolean/blob/master/internal/engine/loader.go"
click node_indexer "https://github.com/cs80-team/goolean/blob/master/internal/engine/indexer.go"
click node_tokenizer "https://github.com/cs80-team/goolean/blob/master/internal/engine/tokenizer/tokenizer.go"
click node_text_processing "https://github.com/cs80-team/goolean/blob/master/internal/textprocessing/textprocessing.go"
click node_query_eval "https://github.com/cs80-team/goolean/blob/master/internal/engine/query.go"
click node_index_manager "https://github.com/cs80-team/goolean/blob/master/internal/engine/index_manager.go"
click node_structures_factory "https://github.com/cs80-team/goolean/blob/master/internal/structures/factory/structures_factory.go"
click node_skip_list_factory "https://github.com/cs80-team/goolean/blob/master/internal/structures/factory/skip_pointer_list_factory.go"
click node_ordered_structures "https://github.com/cs80-team/goolean/tree/master/internal/structures/ordered"
click node_document_store "https://github.com/cs80-team/goolean/blob/master/internal/document.go"
click node_query_transport "https://github.com/cs80-team/goolean/tree/master/internal/transport/query"
click node_file_transport "https://github.com/cs80-team/goolean/tree/master/internal/transport/file"
click node_document_mapper "https://github.com/cs80-team/goolean/blob/master/internal/service/dto/document_mapper.go"

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_main,node_shell_user,node_grpc_client toneBlue
class node_loader,node_indexer,node_tokenizer,node_text_processing,node_filesystem toneAmber
class node_engine,node_query_eval,node_index_manager,node_structures_factory,node_skip_list_factory,node_ordered_structures,node_document_store toneMint
class node_commands,node_query_service,node_file_service,node_uploaded_files,node_query_transport,node_file_transport,node_document_mapper toneRose
```

## Components

### Entry points

- [Application startup](https://github.com/cs80-team/goolean/blob/master/main.go): `main.go`

### Document ingestion

- [Document loader](https://github.com/cs80-team/goolean/blob/master/internal/engine/loader.go): `internal/engine/loader.go`
- [Document indexer](https://github.com/cs80-team/goolean/blob/master/internal/engine/indexer.go): `internal/engine/indexer.go`
- [Tokenizer](https://github.com/cs80-team/goolean/blob/master/internal/engine/tokenizer/tokenizer.go): `internal/engine/tokenizer/tokenizer.go`
- [Text processing](https://github.com/cs80-team/goolean/blob/master/internal/textprocessing/textprocessing.go): `internal/textprocessing/textprocessing.go`

### Search engine

- [Search engine](https://github.com/cs80-team/goolean/blob/master/internal/engine/engine.go): `internal/engine/engine.go`
- [Boolean query evaluation](https://github.com/cs80-team/goolean/blob/master/internal/engine/query.go): `internal/engine/query.go`
- [Inverted index](https://github.com/cs80-team/goolean/blob/master/internal/engine/index_manager.go): `internal/engine/index_manager.go`
- [Index structures factory](https://github.com/cs80-team/goolean/blob/master/internal/structures/factory/structures_factory.go): `internal/structures/factory/structures_factory.go`
- [Skip-list factory](https://github.com/cs80-team/goolean/blob/master/internal/structures/factory/skip_pointer_list_factory.go): `internal/structures/factory/skip_pointer_list_factory.go`
- [Ordered index structures](https://github.com/cs80-team/goolean/tree/master/internal/structures/ordered): `internal/structures/ordered`
- [Indexed documents](https://github.com/cs80-team/goolean/blob/master/internal/document.go): `internal/document.go`

### User interfaces

- [Shell commands](https://github.com/cs80-team/goolean/blob/master/engine_commands.go): `engine_commands.go`
- [Query service](https://github.com/cs80-team/goolean/blob/master/internal/service/query.go): `internal/service/query.go`
- [File service](https://github.com/cs80-team/goolean/blob/master/internal/service/file.go): `internal/service/file.go`
- **Uploaded files**
- [Query gRPC API](https://github.com/cs80-team/goolean/tree/master/internal/transport/query): `internal/transport/query`
- [File gRPC API](https://github.com/cs80-team/goolean/tree/master/internal/transport/file): `internal/transport/file`
- [Document mapper](https://github.com/cs80-team/goolean/blob/master/internal/service/dto/document_mapper.go): `internal/service/dto/document_mapper.go`

### Other components

- **Shell user**
- **gRPC client**
- **Local filesystem**

## Connections

- Shell user → Application startup: starts shell (evidence: `README.md`)
- Application startup → Search engine: configures (evidence: `main.go`)
- Application startup → Shell commands: starts shell (evidence: `main.go`)
- Application startup → Query service: creates (evidence: `main.go`)
- Application startup → File service: creates (evidence: `main.go`)
- gRPC client → Query gRPC API: sends queries (evidence: `README.md`)
- gRPC client → File gRPC API: manages files (evidence: `README.md`)
- Query gRPC API → Query service: routes requests (evidence: `internal/service/query.go`)
- File gRPC API → File service: routes requests (evidence: `internal/service/file.go`)
- Shell commands → Search engine: queries (evidence: `engine_commands.go`)
- Shell commands → Search engine: loads documents (evidence: `engine_commands.go`)
- Query service → Search engine: evaluates query (evidence: `internal/service/query.go`)
- Query service → Document mapper: maps results (evidence: `internal/service/query.go`)
- Document mapper → Query gRPC API: creates response documents (evidence: `internal/service/dto/document_mapper.go`)
- File service → Search engine: indexes upload (evidence: `internal/service/file.go`)
- File service → Local filesystem: writes and reads (evidence: `internal/service/file.go`)
- Search engine → Indexed documents: keeps documents (evidence: `internal/engine/engine.go`)
- Search engine → Document indexer: indexes text
- Search engine → Document loader: loads corpus
- Search engine → Tokenizer: configures tokenization (evidence: `internal/engine/engine.go`)
- Search engine → Text processing: configures processing (evidence: `internal/engine/engine.go`)
- Document indexer → Tokenizer: tokenizes documents (evidence: `internal/engine/indexer.go`)
- Search engine → Boolean query evaluation: evaluates queries (evidence: `internal/engine/query.go`)
- Boolean query evaluation → Inverted index: reads postings (evidence: `internal/engine/query.go`)
- Search engine → Inverted index: manages postings (evidence: `internal/engine/index_manager.go`)
- Inverted index → Index structures factory: creates structures (evidence: `internal/engine/index_manager.go`)
- Skip-list factory → Ordered index structures: creates skip lists (evidence: `internal/structures/factory/skip_pointer_list_factory.go`)
- Index structures factory → Ordered index structures: builds index structures (evidence: `internal/structures/factory/structures_factory.go`)
- Application startup → Skip-list factory: selects implementation (evidence: `main.go`)
- File service → Uploaded files: receives uploads (evidence: `internal/service/file.go`)