smerteliko/knowledge-hub-backend-spring

1. Overall shape

- This is a Spring Boot 3 backend for a personal knowledge system.

- The code follows a classic layered architecture: API controllers → domain/services → persistence repositories → PostgreSQL and Elasticsearch.

- The backend is the system of record for users, notes, links, and tags; Elasticsearch is used as a derived search index.

2. API boundary

- The HTTP layer is split by responsibility into AuthController, ContentController, TagController, SearchController, and LinkParsingController.

- These controllers expose the main user-facing capabilities: authentication, CRUD over knowledge items, tag management, text search, and URL parsing.

- DTOs under dto/* define request/response shapes and keep the API contract separate from internal entities.

3. Authentication and security

- Security is JWT-based, with JwtAuthenticationFilter and SecurityConfig enforcing token validation on protected routes.

- AuthService, JwtService, and JpaUserDetailsService form the authentication backend.

- UserRepository persists users, while Role models authorization scope.

- The architecture is stateless at the API level: login returns a JWT, and subsequent requests carry that token.

4. Core domain model

- The central content model is built around ContentItem, with concrete types Note and Link.

- Tag is a separate domain entity used to classify content items.

- This suggests the system supports mixed knowledge objects but keeps a common content layer for shared operations and search/export logic.

5. Relational persistence

- PostgreSQL is the primary durable store, accessed through Spring Data JPA repositories.

- ContentItemRepository, TagRepository, and UserRepository are the main relational persistence boundaries.

- The database holds authoritative business state, including ownership, relationships, and content metadata.

6. Search subsystem

- Elasticsearch is configured through ElasticsearchConfig and used via LinkSearchRepository and NoteSearchRepository.

- LinkIndex and NoteIndex are separate search documents, indicating the system indexes different content types independently.

- SearchService likely coordinates query execution and relevance behavior across those indices.

- This creates a clear split: PostgreSQL for truth, Elasticsearch for fast full-text retrieval.

7. Content management flow

- ContentService is the orchestration layer for creating and retrieving notes/links.

- Content creation requests come in through NoteCreateRequest and LinkCreateRequest, then are persisted relationally and reflected into search indexing.

- This service boundary is where ownership, tagging, and indexing consistency are likely managed together.

8. URL parsing and enrichment

- LinkParsingService and LinkParsingController handle fetching metadata from external URLs.

- The readme indicates Jsoup is used to extract title, description, and Open Graph tags.

- This is an ingestion/enrichment path: external web pages become structured link objects inside the knowledge hub.

9. Export subsystem

- ExportService is a distinct capability for generating knowledge reports.

- The readme indicates PDF and Markdown output, with Apache PDFBox for PDF generation.

- This is a read-only outbound pipeline that transforms stored knowledge into portable reports.

10. Testing and environment isolation

- Tests are organized by subsystem, with unit and integration coverage for auth, link parsing, and search.

- Test infrastructure includes AbstractTest plus a test-specific Elasticsearch config, indicating environment substitution for search integration tests.

- The readme mentions Testcontainers, so external dependencies such as PostgreSQL and Elasticsearch are likely validated in isolated containers rather than mocks only.

11. Deployment and runtime topology

- The repo includes Dockerfile and compose.yaml, so the application is designed to run as part of a containerized stack.

- The stack includes the Spring app plus PostgreSQL and Elasticsearch, which are the two backing infrastructure services that define the main architecture boundary.

- GitHub Actions workflow exists under .github/workflows/main.yml, suggesting CI builds and tests the same layered stack.

12. Important diagram boundary

- If you draw the architecture, the key separation is: client/API traffic enters the Spring Boot app; business logic lives in services; relational writes go to PostgreSQL; search queries and index writes go to Elasticsearch; outbound enrichment reaches the public web for link parsing; export turns stored content into files.