# kamilwodnicki/hackaton2026 architecture

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

- Interactive diagram: https://gitdiagram.com/kamilwodnicki/hackaton2026
- Repository: https://github.com/kamilwodnicki/hackaton2026

## Overview

This repository combines a social-innovation assistant and discovery platform with semantic search, regional-needs analysis, and data-import pipelines. The main user-facing workflow accepts a chat message, applies crisis checks, gathers project context and county indicators, then requests and filters a language-model response. Separately, the documented search API retrieves and reranks indexed document passages. The frontend also contains account, mentoring, forum, idea, and needs-map surfaces; their runtime wiring is not shown in the sampled evidence, so those are represented without inferred API edges.

Main entry points: [`app/chat.py`](https://github.com/kamilwodnicki/hackaton2026/blob/main/app/chat.py) (Chat API), [`app/main.py`](https://github.com/kamilwodnicki/hackaton2026/blob/main/app/main.py) (Search API), [`scrapers/biblioteka/main.py`](https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/biblioteka/main.py) (Innovation library import), [`scrapers/ioss/main.py`](https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/ioss/main.py) (IOSS import)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web_surfaces["Web surfaces"]
  node_account["Accounts and roles<br/>[auth.js]"]
  node_mentor["Mentoring<br/>[mentor.js]"]
  node_needs_map["Needs map<br/>[mapa-potrzeb.js]"]
  node_ideas["Ideas and forum"]
end

subgraph group_assistant["Assistant services"]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_safety["Safety checks<br/>[guardrails.py]"]
  node_county_analysis["County needs analysis<br/>[ioss_needs.py]"]
end

subgraph group_knowledge["Knowledge search"]
  node_search_api["Search API<br/>[main.py]"]
  node_vector_store[("Qdrant index")]
  node_ingestion["Document ingestion<br/>[ingest.py]"]
end

subgraph group_imports["Data imports"]
  node_biblioteka_import["Innovation library import<br/>[main.py]"]
  node_biblioteka_scraper["Library scraper<br/>[scraper.py]"]
  node_ioss_import["IOSS import<br/>[main.py]"]
  node_ioss_scraper["IOSS scraper<br/>[scraper.py]"]
  node_ioss_writer["IOSS persistence<br/>[database.py]"]
  node_postgres[("PostgreSQL IOSS data")]
end

node_user(("Platform user"))
node_language_model{{"Ollama language model"}}
node_embedding_model{{"Embedding model"}}
node_reranker{{"Cross-encoder reranker"}}
node_source_site{{"Innovation library site"}}

node_user -.->|"sends message"| node_chat_api
node_chat_api -->|"checks crisis"| node_safety
node_chat_api -->|"gets needs"| node_county_analysis
node_chat_api -->|"requests context"| node_search_api
node_chat_api -->|"requests answer"| node_language_model
node_search_api -->|"embeds query"| node_embedding_model
node_search_api -.->|"searches vectors"| node_vector_store
node_search_api -->|"reranks matches"| node_reranker
node_ingestion -->|"writes vectors"| node_vector_store
node_biblioteka_import -->|"runs scraper"| node_biblioteka_scraper
node_biblioteka_scraper -->|"fetches content"| node_source_site
node_biblioteka_import -.->|"supplies index data"| node_ingestion
node_ioss_import -->|"scrapes indicators"| node_ioss_scraper
node_ioss_import -->|"saves results"| node_ioss_writer
node_ioss_writer -->|"writes table"| node_postgres
node_county_analysis -->|"reads indicators"| node_postgres

click node_web_surfaces "https://github.com/kamilwodnicki/hackaton2026/tree/main/frontend"
click node_account "https://github.com/kamilwodnicki/hackaton2026/blob/main/frontend/auth.js"
click node_mentor "https://github.com/kamilwodnicki/hackaton2026/blob/main/frontend/mentor.js"
click node_needs_map "https://github.com/kamilwodnicki/hackaton2026/blob/main/frontend/mapa-potrzeb.js"
click node_ideas "https://github.com/kamilwodnicki/hackaton2026/blob/main/frontend/residents-ideas.html"
click node_chat_api "https://github.com/kamilwodnicki/hackaton2026/blob/main/app/chat.py"
click node_safety "https://github.com/kamilwodnicki/hackaton2026/blob/main/app/guardrails.py"
click node_county_analysis "https://github.com/kamilwodnicki/hackaton2026/blob/main/app/ioss_needs.py"
click node_search_api "https://github.com/kamilwodnicki/hackaton2026/blob/main/app/main.py"
click node_ingestion "https://github.com/kamilwodnicki/hackaton2026/blob/main/app/ingest.py"
click node_biblioteka_import "https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/biblioteka/main.py"
click node_biblioteka_scraper "https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/biblioteka/scraper.py"
click node_ioss_import "https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/ioss/main.py"
click node_ioss_scraper "https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/ioss/scraper.py"
click node_ioss_writer "https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/ioss/database.py"

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_web_surfaces,node_account,node_mentor,node_needs_map,node_ideas,node_user toneBlue
class node_chat_api,node_safety,node_county_analysis toneAmber
class node_search_api,node_vector_store,node_ingestion toneMint
class node_biblioteka_import,node_biblioteka_scraper,node_ioss_import,node_ioss_scraper,node_ioss_writer,node_postgres toneRose
class node_language_model,node_embedding_model,node_reranker,node_source_site toneIndigo
```

## Components

### User experience

- [Web surfaces](https://github.com/kamilwodnicki/hackaton2026/tree/main/frontend): `frontend`
- [Accounts and roles](https://github.com/kamilwodnicki/hackaton2026/blob/main/frontend/auth.js): `frontend/auth.js`
- [Mentoring](https://github.com/kamilwodnicki/hackaton2026/blob/main/frontend/mentor.js): `frontend/mentor.js`
- [Needs map](https://github.com/kamilwodnicki/hackaton2026/blob/main/frontend/mapa-potrzeb.js): `frontend/mapa-potrzeb.js`
- [Ideas and forum](https://github.com/kamilwodnicki/hackaton2026/blob/main/frontend/residents-ideas.html): `frontend/residents-ideas.html`

### Assistant services

- [Chat API](https://github.com/kamilwodnicki/hackaton2026/blob/main/app/chat.py): `app/chat.py`
- [Safety checks](https://github.com/kamilwodnicki/hackaton2026/blob/main/app/guardrails.py): `app/guardrails.py`
- [County needs analysis](https://github.com/kamilwodnicki/hackaton2026/blob/main/app/ioss_needs.py): `app/ioss_needs.py`

### Knowledge search

- [Search API](https://github.com/kamilwodnicki/hackaton2026/blob/main/app/main.py): `app/main.py`
- **Qdrant index**
- [Document ingestion](https://github.com/kamilwodnicki/hackaton2026/blob/main/app/ingest.py): `app/ingest.py`

### Data imports

- [Innovation library import](https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/biblioteka/main.py): `scrapers/biblioteka/main.py`
- [Library scraper](https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/biblioteka/scraper.py): `scrapers/biblioteka/scraper.py`
- [IOSS import](https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/ioss/main.py): `scrapers/ioss/main.py`
- [IOSS scraper](https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/ioss/scraper.py): `scrapers/ioss/scraper.py`
- [IOSS persistence](https://github.com/kamilwodnicki/hackaton2026/blob/main/scrapers/ioss/database.py): `scrapers/ioss/database.py`
- **PostgreSQL IOSS data**

### Other components

- **Platform user**
- **Ollama language model**
- **Embedding model**
- **Cross-encoder reranker**
- **Innovation library site**

## Connections

- Platform user → Chat API: sends message
- Chat API → Safety checks: checks crisis (evidence: `app/chat.py`)
- Chat API → County needs analysis: gets needs (evidence: `app/chat.py`)
- Chat API → Search API: requests context (evidence: `app/chat.py`)
- Chat API → Ollama language model: requests answer (evidence: `app/chat.py`)
- Search API → Embedding model: embeds query (evidence: `app/main.py`)
- Search API → Qdrant index: searches vectors (evidence: `README.md`)
- Search API → Cross-encoder reranker: reranks matches (evidence: `app/main.py`)
- Document ingestion → Qdrant index: writes vectors (evidence: `app/ingest.py`)
- Innovation library import → Library scraper: runs scraper (evidence: `scrapers/biblioteka/main.py`)
- Library scraper → Innovation library site: fetches content (evidence: `scrapers/biblioteka/scraper.py`)
- Innovation library import → Document ingestion: supplies index data (evidence: `README.md`)
- IOSS import → IOSS scraper: scrapes indicators (evidence: `scrapers/ioss/main.py`)
- IOSS import → IOSS persistence: saves results (evidence: `scrapers/ioss/main.py`)
- IOSS persistence → PostgreSQL IOSS data: writes table (evidence: `scrapers/ioss/database.py`)
- County needs analysis → PostgreSQL IOSS data: reads indicators (evidence: `app/ioss_needs.py`)
