# kakaotechcampus-4/ktc4-pusan-4 architecture

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

- Interactive diagram: https://gitdiagram.com/kakaotechcampus-4/ktc4-pusan-4
- Repository: https://github.com/kakaotechcampus-4/ktc4-pusan-4

## Overview

PreeT helps sole proprietors judge card expenses for tax deductibility. The user uploads a card statement, reviews unresolved merchant-category suggestions, supplies business context and answers only needed follow-up questions, then sees cited decisions, annual-limit effects, summaries, and a tax-adviser export. Judgment is deterministic; AI supports merchant suggestions, the Really assistant, and rule-candidate drafting. The README documents these product flows and corpus sync; sampled code confirms selected judgment, query, classification-review, and AI-server behavior. Other links are limited to documented relationships because their implementations were not sampled.

Main entry points: [`frontend/src/App.tsx`](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/frontend/src/App.tsx) (PreeT web app), [`backend/src/main/java/com/ktc4/pusan4/transaction/persistence/ClassificationReviewService.java`](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/transaction/persistence/ClassificationReviewService.java) (Category review), [`ai/classify/decisions.py`](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/classify/decisions.py) (AI category suggestions), [`ai/assistant/agent.py`](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/assistant/agent.py) (Really assistant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User experience"]
  node_web["PreeT web app<br/>[App.tsx]"]
  node_statement["Statement parser<br/>[pipeline.ts]"]
end

subgraph group_transactions["Transactions and classification"]
  node_upload["Transaction API"]
  node_transaction_store[("Transaction records")]
  node_merchant_classify["Merchant classifier"]
  node_review["Category review"]
end

subgraph group_judgment["Expense judgment"]
  node_context["Business context"]
  node_engine["Rules judgment engine"]
  node_judgment_store[("Judgment records")]
  node_questions["Follow-up questions"]
  node_results["Results and export"]
end

subgraph group_ai_ops["AI and rule operations"]
  node_ai_classify["AI category suggestions<br/>[decisions.py]"]
  node_assistant["Really assistant<br/>[agent.py]"]
  node_assistant_tools["Assistant API tools<br/>[tools.py]"]
  node_candidate["Rule candidates<br/>[candidates.py]"]
  node_corpus["Law corpus sync<br/>[law_sync.py]"]
  node_promotion["Rule-card promotion<br/>[promote.py]"]
  node_ai_server["AI service<br/>[main.py]"]
end

subgraph group_identity["Identity and support"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_user_store[("User and business data<br/>[UserService.java]")]
  node_redis[("Redis token store")]
end

node_user(("Business owner"))
node_law_service["National law API"]
node_llm["LLM provider"]
node_github["GitHub rules PR"]

node_user -->|"uses"| node_web
node_web -->|"reads statement"| node_statement
node_statement -->|"submits transactions"| node_upload
node_upload -.->|"stores transactions"| node_transaction_store
node_transaction_store -.->|"classifies merchants"| node_merchant_classify
node_merchant_classify -.->|"requests suggestions"| node_ai_classify
node_ai_classify -->|"served by"| node_ai_server
node_ai_classify -->|"requests categories"| node_llm
node_web -->|"confirms categories"| node_review
node_review -->|"updates classifications"| node_transaction_store
node_review -->|"rejudges transactions"| node_engine
node_web -->|"sets business context"| node_context
node_engine -.->|"persists decisions"| node_judgment_store
node_web -->|"answers questions"| node_questions
node_questions -->|"reads judgments"| node_judgment_store
node_web -->|"views and exports"| node_results
node_results -->|"queries judgments"| node_judgment_store
node_web -->|"asks questions"| node_assistant
node_assistant -.->|"uses tools"| node_assistant_tools
node_assistant_tools -.->|"runs in"| node_ai_server
node_assistant -.->|"generates answers"| node_llm
node_candidate -->|"retrieves law sources"| node_corpus
node_corpus -->|"syncs statutes"| node_law_service
node_user -->|"reviews candidates"| node_web
node_web -->|"approves candidates"| node_candidate
node_candidate -->|"approved drafts"| node_promotion
node_promotion -->|"opens rules PR"| node_github
node_user -->|"signs in"| node_web
node_web -.->|"authenticates"| node_auth
node_auth -->|"manages accounts"| node_user_store
node_auth -->|"stores refresh tokens"| node_redis

click node_web "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/frontend/src/App.tsx"
click node_statement "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/frontend/src/parser/pipeline.ts"
click node_upload "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/transaction/api/UploadBatchController.java"
click node_transaction_store "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/judgment/persistence/TransactionRecordEntity.java"
click node_merchant_classify "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/merchant/classify/MerchantClassifier.java"
click node_ai_classify "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/classify/decisions.py"
click node_review "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/transaction/persistence/ClassificationReviewService.java"
click node_context "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/user/persistence/BusinessContextService.java"
click node_engine "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/judgment/domain/JudgmentEngine.java"
click node_judgment_store "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/judgment/persistence/JudgmentEntity.java"
click node_questions "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/judgment/persistence/QuestionQueryService.java"
click node_results "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/judgment/persistence/JudgmentQueryService.java"
click node_assistant "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/assistant/agent.py"
click node_assistant_tools "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/assistant/tools.py"
click node_candidate "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/pipeline/candidates.py"
click node_corpus "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/pipeline/law_sync.py"
click node_promotion "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/pipeline/promote.py"
click node_auth "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/auth/AuthService.java"
click node_user_store "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/user/persistence/UserService.java"
click node_redis "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/auth/RedisRefreshTokenStore.java"
click node_ai_server "https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/app/main.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,node_statement toneBlue
class node_upload,node_transaction_store,node_merchant_classify,node_review toneAmber
class node_context,node_engine,node_judgment_store,node_questions,node_results,node_law_service toneMint
class node_ai_classify,node_assistant,node_assistant_tools,node_candidate,node_corpus,node_promotion,node_ai_server toneRose
class node_auth,node_user_store,node_redis,node_user,node_llm,node_github toneIndigo
```

## Components

### User experience

- [PreeT web app](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Statement parser](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/frontend/src/parser/pipeline.ts): `frontend/src/parser/pipeline.ts`

### Transactions and classification

- [Transaction API](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/transaction/api/UploadBatchController.java): `backend/src/main/java/com/ktc4/pusan4/transaction/api/UploadBatchController.java`
- [Transaction records](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/judgment/persistence/TransactionRecordEntity.java): `backend/src/main/java/com/ktc4/pusan4/judgment/persistence/TransactionRecordEntity.java`
- [Merchant classifier](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/merchant/classify/MerchantClassifier.java): `backend/src/main/java/com/ktc4/pusan4/merchant/classify/MerchantClassifier.java`
- [Category review](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/transaction/persistence/ClassificationReviewService.java): `backend/src/main/java/com/ktc4/pusan4/transaction/persistence/ClassificationReviewService.java`

### Expense judgment

- [Business context](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/user/persistence/BusinessContextService.java): `backend/src/main/java/com/ktc4/pusan4/user/persistence/BusinessContextService.java`
- [Rules judgment engine](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/judgment/domain/JudgmentEngine.java): `backend/src/main/java/com/ktc4/pusan4/judgment/domain/JudgmentEngine.java`
- [Judgment records](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/judgment/persistence/JudgmentEntity.java): `backend/src/main/java/com/ktc4/pusan4/judgment/persistence/JudgmentEntity.java`
- [Follow-up questions](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/judgment/persistence/QuestionQueryService.java): `backend/src/main/java/com/ktc4/pusan4/judgment/persistence/QuestionQueryService.java`
- [Results and export](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/judgment/persistence/JudgmentQueryService.java): `backend/src/main/java/com/ktc4/pusan4/judgment/persistence/JudgmentQueryService.java`

### AI and rule operations

- [AI category suggestions](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/classify/decisions.py): `ai/classify/decisions.py`
- [Really assistant](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/assistant/agent.py): `ai/assistant/agent.py`
- [Assistant API tools](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/assistant/tools.py): `ai/assistant/tools.py`
- [Rule candidates](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/pipeline/candidates.py): `ai/pipeline/candidates.py`
- [Law corpus sync](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/pipeline/law_sync.py): `ai/pipeline/law_sync.py`
- [Rule-card promotion](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/pipeline/promote.py): `ai/pipeline/promote.py`
- [AI service](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/ai/app/main.py): `ai/app/main.py`

### Identity and support

- [Authentication](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/auth/AuthService.java): `backend/src/main/java/com/ktc4/pusan4/auth/AuthService.java`
- [User and business data](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/user/persistence/UserService.java): `backend/src/main/java/com/ktc4/pusan4/user/persistence/UserService.java`
- [Redis token store](https://github.com/kakaotechcampus-4/ktc4-pusan-4/blob/develop/backend/src/main/java/com/ktc4/pusan4/auth/RedisRefreshTokenStore.java): `backend/src/main/java/com/ktc4/pusan4/auth/RedisRefreshTokenStore.java`

### Other components

- **Business owner**
- **National law API**
- **LLM provider**
- **GitHub rules PR**

## Connections

- Business owner → PreeT web app: uses (evidence: `README.md`)
- PreeT web app → Statement parser: reads statement (evidence: `README.md`)
- Statement parser → Transaction API: submits transactions (evidence: `README.md`)
- Transaction API → Transaction records: stores transactions
- Transaction records → Merchant classifier: classifies merchants
- Merchant classifier → AI category suggestions: requests suggestions
- AI category suggestions → AI service: served by (evidence: `ai/app/main.py`)
- AI category suggestions → LLM provider: requests categories
- PreeT web app → Category review: confirms categories (evidence: `README.md`)
- Category review → Transaction records: updates classifications (evidence: `backend/src/main/java/com/ktc4/pusan4/transaction/persistence/ClassificationReviewService.java`)
- Category review → Rules judgment engine: rejudges transactions (evidence: `backend/src/main/java/com/ktc4/pusan4/transaction/persistence/ClassificationReviewService.java`)
- PreeT web app → Business context: sets business context (evidence: `README.md`)
- Rules judgment engine → Judgment records: persists decisions
- PreeT web app → Follow-up questions: answers questions (evidence: `README.md`)
- Follow-up questions → Judgment records: reads judgments (evidence: `backend/src/main/java/com/ktc4/pusan4/judgment/persistence/QuestionQueryService.java`)
- PreeT web app → Results and export: views and exports (evidence: `README.md`)
- Results and export → Judgment records: queries judgments (evidence: `backend/src/main/java/com/ktc4/pusan4/judgment/persistence/JudgmentQueryService.java`)
- PreeT web app → Really assistant: asks questions (evidence: `README.md`)
- Really assistant → Assistant API tools: uses tools (evidence: `ai/assistant/agent.py`)
- Assistant API tools → AI service: runs in
- Really assistant → LLM provider: generates answers
- Rule candidates → Law corpus sync: retrieves law sources (evidence: `README.md`)
- Law corpus sync → National law API: syncs statutes (evidence: `README.md`)
- Business owner → PreeT web app: reviews candidates (evidence: `README.md`)
- PreeT web app → Rule candidates: approves candidates (evidence: `README.md`)
- Rule candidates → Rule-card promotion: approved drafts (evidence: `README.md`)
- Rule-card promotion → GitHub rules PR: opens rules PR (evidence: `README.md`)
- Business owner → PreeT web app: signs in (evidence: `README.md`)
- PreeT web app → Authentication: authenticates
- Authentication → User and business data: manages accounts (evidence: `backend/src/main/java/com/ktc4/pusan4/auth/AuthService.java`)
- Authentication → Redis token store: stores refresh tokens (evidence: `README.md`)
