Skip to content

univCabi/BE

BranchesTags

Repository files navigation

univCabi - Backend

대학 사물함(캐비닛) 대여 관리 시스템의 백엔드 서버입니다. Django 프레임워크를 기반으로 Clean Architecture 원칙을 적용하고, Celery + Redis + Kafka를 활용한 대규모 트래픽 처리 및 블록체인 기반 이력 관리 기능을 제공합니다.

Backend Architecture Structure

본 프로젝트의 백엔드는 복잡한 비즈니스 로직을 효율적으로 처리하고, 유지보수성과 확장성을 확보하기 위해 다음과 같은 아키텍처 설계를 적용했습니다.

Key Architectural Concepts

Django-Based Layered Architecture

Django 프레임워크의 강점(ORM, Admin, Middleware)을 유지하면서도 Clean Architecture 원칙을 적용하여 비즈니스 로직을 프레임워크로부터 분리했습니다.

graph TD
    subgraph Presentation ["Presentation Layer"]
        Views["API Views (DRF)"]
        Serializers["Serializers"]
        DTOs["Request DTOs"]
        Middleware["Middleware (JWT, CORS)"]
    end

    subgraph Business ["Business Logic Layer"]
        CabinetService["Cabinet Service"]
        BlockchainService["Blockchain Service"]
        HistoryService["History Service"]
        BookmarkService["Bookmark Service"]
    end

    subgraph Persistence ["Persistence Layer"]
        Repository["Repository Pattern"]
        Models["Django Models (ORM)"]
    end

    subgraph Infrastructure ["Infrastructure Layer"]
        Celery["Celery Tasks"]
        Redis["Redis Cache & Lock"]
        Kafka["Kafka Producer/Consumer"]
        ThreadPool["Custom Thread Pool"]
        Blockchain["Web3 Provider"]
    end

    subgraph Database
        DB[("PostgreSQL / SQLite")]
        RedisDB[("Redis")]
        ETH[("Ethereum Sepolia")]
    end

    %% Flow
    Views --> DTOs
    Views --> Business
    Business --> Repository
    Repository --> Models
    Models --> DB

    Business --> Infrastructure
    Celery --> RedisDB
    Redis --> RedisDB
    Kafka --> Business
    Blockchain --> ETH
Loading

Triple-Redundancy Async Processing Architecture

대규모 트래픽 처리를 위해 3단계 병렬 처리 아키텍처를 구현했습니다:

sequenceDiagram
    participant Client
    participant API as Django API
    participant TP as Thread Pool
    participant Celery
    participant Kafka
    participant Redis
    participant DB as Database

    Client->>API: POST /cabinet/rent

    par Primary Processing
        API->>TP: Submit to Thread Pool
        TP->>Redis: Acquire Distributed Lock
        Redis-->>TP: Lock Acquired
        TP->>DB: Process Rental
        TP->>Redis: Store Result
    and Secondary Processing
        API->>Celery: Enqueue Task
        Celery->>Redis: Acquire Lock
        Celery->>DB: Process Rental (if needed)
    and Tertiary Processing
        API->>Kafka: Publish Event
        Kafka->>Kafka: Consumer Group Listens
        Kafka->>DB: Process Rental (if needed)
    end

    API->>Redis: Poll for Result
    Redis-->>API: Return Result
    API-->>Client: Response
Loading

각 계층의 역할:

  1. Thread Pool (Primary) - 가장 빠른 응답 속도

    • 애플리케이션 내부 스레드 풀 (5 workers)
    • 즉각적인 처리로 평균 응답시간 최소화
    • 경량 작업에 최적화

  2. Celery (Secondary) - 안정성과 확장성

    • Redis 기반 분산 작업 큐
    • Thread Pool 과부하 시 자동 처리
    • 재시도 로직 및 작업 스케줄링

  3. Kafka (Tertiary) - 장애 복구 및 이벤트 스트리밍

    • 메시지 영속성 보장
    • Consumer Group을 통한 수평 확장
    • 시스템 장애 시에도 이벤트 손실 방지

Distributed Locking Strategy

Redis를 활용한 분산 락으로 동시성 문제를 해결했습니다:

graph LR
    subgraph Users
        U1[User A]
        U2[User B]
        U3[User C]
    end

    subgraph RedisLock [Redis Distributed Lock]
        Lock["cabinet:123:rent
        (UUID: abc-def-123)
        TTL: 30s"]
    end

    subgraph Processing
        Winner[User A Processing]
        Queue[Users B & C Waiting]
    end

    U1 -->|Acquire Lock ✓| Lock
    U2 -->|Try Lock ✗| Lock
    U3 -->|Try Lock ✗| Lock

    Lock -->|Lock Acquired| Winner
    Lock -.->|Blocked| Queue

    Winner -->|Release Lock| Lock
    Queue -->|Next User Acquires| Lock
Loading

구현 특징:

  • UUID 기반 소유권 검증
  • 자동 TTL로 데드락 방지
  • 사물함별 독립적인 락 (세밀한 동시성 제어)

Blockchain-Based Audit Trail

블록체인(Ethereum)을 활용한 변조 불가능한 대여 이력 관리:

graph TD
    subgraph DjangoBackend [Django Backend]
        Rental[Cabinet Rental Event]
        History[Create cabinet_histories record]
    end

    subgraph BlockchainService [Blockchain Service]
        Web3[Web3.py Provider]
        Mint[Mint NFT Function]
    end

    subgraph EthereumNetwork [Ethereum Sepolia Testnet]
        Contract[CabinetHistoryNFT.sol
        ERC-721 Contract]
        NFT[NFT Token
        TokenId = history.id]
    end

    subgraph NFTMetadata [NFT Metadata]
        Data["cabinetId: 123
        historyId: 456
        userAddress: 0x...
        rentedAt: timestamp
        expiredAt: timestamp"]
    end

    Rental --> History
    History --> Mint
    Mint --> Web3
    Web3 --> Contract
    Contract --> NFT
    NFT --> Data
Loading

활용 사례:

  • 학생의 사물함 사용 이력을 블록체인에 영구 기록
  • 대여/반납 시점의 변조 방지
  • 투명한 관리 기록 및 감사 추적
  • NFT 기반 디지털 증명서 발급

Traffic Handling Strategy

고성능 처리 기법

Redis 기반 즐겨찾기 버퍼링

sequenceDiagram
    participant User
    participant API
    participant Redis
    participant CeleryBeat
    participant DB

    User->>API: POST /cabinet/bookmark/add
    API->>Redis: SADD bookmarks:{user_id} {cabinet_id}
    Redis-->>API: OK (1-2ms)
    API-->>User: Success (즉시 응답)

    Note over CeleryBeat: Every 5 seconds
    CeleryBeat->>Redis: SMEMBERS bookmarks:*
    Redis-->>CeleryBeat: Return all bookmarks
    CeleryBeat->>DB: Bulk INSERT/UPDATE
    DB-->>CeleryBeat: Committed
Loading

동시성 제어를 통한 데이터 정합성

시나리오: 100000명의 사용자가 동시에 같은 사물함 대여 시도

graph TD
    U1[User 1] -->|Try Lock| Lock[Redis Lock: cabinet:123]
    U2[User 2] -->|Try Lock| Lock
    U3[User 3...100000] -->|Try Lock| Lock

    Lock -->|Acquired| U1
    Lock -.->|Blocked| U2
    Lock -.->|Blocked| U3

    U1 -->|Process Rental| DB[(Database)]
    U1 -->|Release Lock| Lock

    Lock -->|Next Acquire| U2
    U2 -.->|Already Rented Error| U2
Loading

Database Schema

ERD (Entity Relationship Diagram)

erDiagram
    authns ||--|| users : "OneToOne"
    buildings ||--o{ cabinets : "has many"
    buildings ||--o{ users : "preferred by"
    users ||--o{ cabinets : "currently renting"
    users ||--o{ cabinet_histories : "rental history"
    users ||--o{ cabinet_bookmarks : "bookmarks"
    cabinets ||--|| cabinet_positions : "has position"
    cabinets ||--o{ cabinet_histories : "history"
    cabinets ||--o{ cabinet_bookmarks : "bookmarked by"

    authns {
        bigint id PK
        string student_number UK "학번"
        string password "해시된 비밀번호"
        string role "NORMAL/ADMIN"
        datetime created_at
        datetime updated_at
    }

    users {
        bigint id PK
        string name "사용자 이름"
        string affiliation "소속"
        string phone_number "연락처"
        bigint building_id FK "선호 건물"
        boolean is_visible "공개 여부"
        datetime created_at
        datetime updated_at
    }

    buildings {
        bigint id PK
        string name "건물명 (Enum)"
        int floor "층수"
        string section "구역"
        int width "사물함 배치 가로"
        int height "사물함 배치 세로"
    }

    cabinets {
        bigint id PK
        string cabinet_number "사물함 번호"
        string status "AVAILABLE/USING/BROKEN/OVERDUE"
        bigint user_id FK "현재 사용자"
        bigint building_id FK "소속 건물"
        boolean payable "유료 여부"
        string reason "사용 불가 사유"
        datetime created_at
        datetime updated_at
    }

    cabinet_positions {
        bigint id PK
        bigint cabinet_id FK "사물함"
        int cabinet_x_pos "X 좌표"
        int cabinet_y_pos "Y 좌표"
    }

    cabinet_histories {
        bigint id PK
        bigint user_id FK "대여자"
        bigint cabinet_id FK "사물함"
        datetime created_at "대여 시작일"
        datetime expired_at "만료 예정일"
        datetime ended_at "실제 반납일"
    }

    cabinet_bookmarks {
        bigint id PK
        bigint user_id FK "사용자"
        bigint cabinet_id FK "사물함"
        boolean is_deleted "삭제 여부"
        datetime created_at
        datetime updated_at
    }
Loading

Technology Stack

Backend Framework

  • Django: 5.2.1
  • Django REST Framework: 3.15.2
  • Python: 3.10+

Authentication

  • djangorestframework-simplejwt: 5.4.0

Database

  • Development: SQLite3
  • Production: PostgreSQL (지원)
  • ORM: Django ORM

Caching & Message Queue

  • Redis: 5.2.1
  • django-redis: 5.4.0
  • Celery: 5.5.2
  • kafka-python: 2.1.5

Blockchain

  • Web3.py: 7.11.0
  • Solidity: ^0.8.0
  • Network: Ethereum Sepolia Testnet
  • Provider: Infura

API Documentation

  • drf-yasg: 1.21.8 (Swagger/OpenAPI)

Development Tools

  • django-environ: 0.11.2 (환경 변수 관리)
  • django-cors-headers: 4.6.0 (CORS)

🧑🏻‍💻 프로젝트 멤버

이름 역할 GitHub
민영재 PM, Backend, Frontend, Design yeomin4242
민웅기 Backend, Frontend, Design minwoonggi
김주희 Frontend, Design joooii

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages