๐ŸŒ AIๆœ็ดข & ไปฃ็† ไธป้กต
Skip to content

AI lottery recommendation backend service based on four pillars using Clean Architecture and FastAPI

Notifications You must be signed in to change notification settings

Nexters/Satto-Server

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

30 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Satto Server

์‚ฌ์ฃผ ๊ธฐ๋ฐ˜ ์šด์„ธ ๋ฐ ๋กœ๋˜ ์ถ”์ฒœ ์„œ๋น„์Šค ๋ฐฑ์—”๋“œ

์•„ํ‚คํ…์ฒ˜

์ด ํ”„๋กœ์ ํŠธ๋Š” Clean Architecture ํŒจํ„ด์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค.

๋ ˆ์ด์–ด ๊ตฌ์กฐ

๊ฐ ๋ชจ๋“ˆ(users, lotto, fortune ๋“ฑ)์€ ๋‹ค์Œ๊ณผ ๊ฐ™์€ ๋ ˆ์ด์–ด ๊ตฌ์กฐ๋ฅผ ๊ฐ€์ง‘๋‹ˆ๋‹ค:

{module}/
โ”œโ”€โ”€ api/                    # API ๋ ˆ์ด์–ด (ํ”„๋ ˆ์  ํ…Œ์ด์…˜)
โ”‚   โ”œโ”€โ”€ router.py          # FastAPI ๋ผ์šฐํ„ฐ (์—”๋“œํฌ์ธํŠธ ์ •์˜)
โ”‚   โ””โ”€โ”€ schemas.py         # ์š”์ฒญ/์‘๋‹ต ์Šคํ‚ค๋งˆ (Pydantic ๋ชจ๋ธ)
โ”‚
โ”œโ”€โ”€ application/            # ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ๋ ˆ์ด์–ด (Use Case)
โ”‚   โ””โ”€โ”€ service.py         # ๋น„์ฆˆ๋‹ˆ์Šค ๋กœ์ง ๊ตฌํ˜„, ๋„๋ฉ”์ธ ์กฐํ•ฉ
โ”‚
โ”œโ”€โ”€ domain/                 # ๋„๋ฉ”์ธ ๋ ˆ์ด์–ด (๋น„์ฆˆ๋‹ˆ์Šค ๊ทœ์น™)
โ”‚   โ”œโ”€โ”€ entities/          # ๋„๋ฉ”์ธ ์—”ํ‹ฐํ‹ฐ
โ”‚   โ”‚   โ”œโ”€โ”€ models.py      # SQLAlchemy ๋ชจ๋ธ
โ”‚   โ”‚   โ””โ”€โ”€ enums.py       # ๋„๋ฉ”์ธ Enum
โ”‚   โ””โ”€โ”€ interfaces.py      # ๋ฆฌํฌ์ง€ํ† ๋ฆฌ ์ธํ„ฐํŽ˜์ด์Šค (Protocol)
โ”‚
โ””โ”€โ”€ infrastructure/         # ์ธํ”„๋ผ ๋ ˆ์ด์–ด (๊ตฌํ˜„)
    โ””โ”€โ”€ repository.py      # ๋ฆฌํฌ์ง€ํ† ๋ฆฌ ๊ตฌํ˜„ (๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ ‘๊ทผ)

๊ฐ ๋ ˆ์ด์–ด์˜ ์—ญํ• 

API Layer (api/)

  • HTTP ์š”์ฒญ/์‘๋‹ต ์ฒ˜๋ฆฌ
  • FastAPI ๋ผ์šฐํ„ฐ๋ฅผ ํ†ตํ•œ ์—”๋“œํฌ์ธํŠธ ์ •์˜
  • ์š”์ฒญ ๊ฒ€์ฆ ๋ฐ ์‘๋‹ต ์ง๋ ฌํ™”
  • ์˜ˆ: @router.get("/users/{user_id}") ์—”๋“œํฌ์ธํŠธ ์ •์˜

Application Layer (application/)

  • Use Case ๊ตฌํ˜„
  • ๋„๋ฉ”์ธ ๋กœ์ง ์กฐํ•ฉ ๋ฐ ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ด์…˜
  • ํŠธ๋žœ์žญ์…˜ ๊ด€๋ฆฌ
  • ์˜ˆ: UserService.create_user() - ์‚ฌ์šฉ์ž ์ƒ์„ฑ Use Case

Domain Layer (domain/)

  • ๋น„์ฆˆ๋‹ˆ์Šค ๊ทœ์น™ ๋ฐ ๋„๋ฉ”์ธ ๋ชจ๋ธ
  • ์™ธ๋ถ€ ์˜์กด์„ฑ ์—†์Œ (์ˆœ์ˆ˜ ๋น„์ฆˆ๋‹ˆ์Šค ๋กœ์ง)
  • ์ธํ„ฐํŽ˜์ด์Šค ์ •์˜ (์˜์กด์„ฑ ์—ญ์ „ ์›์น™)
  • ์˜ˆ: IUserRepository ์ธํ„ฐํŽ˜์ด์Šค, User ์—”ํ‹ฐํ‹ฐ

Infrastructure Layer (infrastructure/)

  • ์™ธ๋ถ€ ์‹œ์Šคํ…œ๊ณผ์˜ ํ†ต์‹  ๊ตฌํ˜„
  • ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ ‘๊ทผ ๊ตฌํ˜„
  • ์™ธ๋ถ€ API ํด๋ผ์ด์–ธํŠธ
  • ์˜ˆ: UserRepository - MySQL ์ ‘๊ทผ ๊ตฌํ˜„

์˜์กด์„ฑ ๋ฐฉํ–ฅ

API โ†’ Application โ†’ Domain โ† Infrastructure
  • Domain: ๊ฐ€์žฅ ์•ˆ์ชฝ ๋ ˆ์ด์–ด, ์™ธ๋ถ€ ์˜์กด์„ฑ ์—†์Œ
  • Application: Domain์„ ์‚ฌ์šฉํ•˜์—ฌ ๋น„์ฆˆ๋‹ˆ์Šค ๋กœ์ง ๊ตฌํ˜„
  • Infrastructure: Domain ์ธํ„ฐํŽ˜์ด์Šค๋ฅผ ๊ตฌํ˜„
  • API: Application์„ ํ˜ธ์ถœํ•˜์—ฌ HTTP ์š”์ฒญ ์ฒ˜๋ฆฌ

Main Modules

users

  • ์‚ฌ์šฉ์ž ์ƒ์„ฑ/์กฐํšŒ/์ˆ˜์ •
  • ์‚ฌ์ฃผ ์ •๏ฟฝ๏ฟฝ๏ฟฝ ์ €์žฅ ๋ฐ ์กฐํšŒ

four_pillars

  • ์ƒ๋…„์›”์ผ ๊ธฐ๋ฐ˜ ์‚ฌ์ฃผ ๊ณ„์‚ฐ
  • ์˜คํ–‰, ์‹ญ์‹  ๋ถ„์„
  • HCX API๋ฅผ ํ†ตํ•œ ์‚ฌ์ฃผ ์„ค๋ช… ์ƒ์„ฑ

fortune

  • ์ผ์ผ ์šด์„ธ ์ œ๊ณต
  • ์‚ฌ์ฃผ ๊ธฐ๋ฐ˜ ์šด์„ธ ๋ถ„์„

lotto

  • ์‚ฌ์ฃผ ๊ธฐ๋ฐ˜ ๋กœ๋˜ ๋ฒˆํ˜ธ ์ถ”์ฒœ
  • ๋กœ๋˜ ํ†ต๊ณ„ ๋ฐ ๋‹น์ฒจ ํ™•์ธ

Local Server Settings

Requirements

  • Python 3.13+
  • MySQL
  • uv (ํŒจํ‚ค์ง€ ๊ด€๋ฆฌ์ž)

ํ™˜๊ฒฝ ์„ธํŒ…

# ์˜์กด์„ฑ ์„ค์น˜
uv sync

# ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ์„ค์ •
cp .env.example .env

์‹คํ–‰

docker-compose -f docker-compose.local.yml up --build

์ „์ฒด ํ”„๋กœ์ ํŠธ ๊ตฌ์กฐ

Satto-Server/
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ users/          # ์‚ฌ์šฉ์ž ๋ชจ๋“ˆ
โ”‚   โ”œโ”€โ”€ four_pillars/   # ์‚ฌ์ฃผ ๊ณ„์‚ฐ ๋ชจ๋“ˆ
โ”‚   โ”œโ”€โ”€ fortune/        # ์šด์„ธ ๋ชจ๋“ˆ
โ”‚   โ”œโ”€โ”€ lotto/          # ๋กœ๋˜ ์ถ”์ฒœ ๋ชจ๋“ˆ
โ”‚   โ”œโ”€โ”€ hcx_client/     # HCX API ํด๋ผ์ด์–ธํŠธ
โ”‚   โ”œโ”€โ”€ config/         # ์„ค์ •
โ”‚   โ””โ”€โ”€ common/         # ๊ณตํ†ต ์œ ํ‹ธ๋ฆฌํ‹ฐ
โ”œโ”€โ”€ migrations/          # ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜
โ”œโ”€โ”€ nginx/              # Nginx ์„ค์ •
โ””โ”€โ”€ pyproject.toml      # ํ”„๋กœ์ ํŠธ ์„ค์ •

๊ธฐ์ˆ  ์Šคํƒ

  • Framework: FastAPI
  • Database: MySQL (SQLAlchemy)
  • Migration: Alembic
  • Package Manager: uv
  • Code Quality: ruff, mypy

Development

์ฝ”๋“œ ํฌ๋งทํŒ…

ruff format .
ruff check .

ํƒ€์ž… ์ฒดํฌ

mypy src/

๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜

# ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ์ƒ์„ฑ
alembic revision --autogenerate -m "description"

# ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ์ ์šฉ
alembic upgrade head

About

AI lottery recommendation backend service based on four pillars using Clean Architecture and FastAPI

Resources

Stars

Watchers

Forks

Languages