How fcherchyk/kambi works
Kambi is a local, single-user kanban app. A user signs in, manages boards and their columns and card types, then creates, edits, orders, moves, archives, and restores cards and columns through the SPA and FastAPI API. The API enforces session ownership and version checks while persisting domain state in PostgreSQL. The diagram preserves the documented archive, keyboard, and optimistic-update UI capabilities; source excerpts are incomplete, so some documented links use the README as evidence.
Main entry points: db.py Database sessions · service.py Board management · BoardPage.tsx Board workspace · main.py FastAPI app
Components 27
Web interface
- SPA shell
web/src/App.tsx - Boards list
web/src/pages/BoardsPage.tsx - Board workspace
web/src/pages/BoardPage.tsx - Board state
web/src/board/useBoard.ts - Column and cards
web/src/board/ColumnView.tsx - Archive view
web/src/pages/ArchivePage.tsx - Card types panel
web/src/board/CardTypesPanel.tsx - Keyboard shortcuts
web/src/keyboard/shortcuts.ts - API client
web/src/api/client.ts
API and authentication
- FastAPI app
api/app/main.py - Google sign-in
api/app/auth/google.py - Sessions and identity
api/app/auth/sessions.py - Request authentication
api/app/auth/dependencies.py
Board domain
- Board management
api/app/boards/service.py - Column lifecycle
api/app/columns/service.py - Card lifecycle
api/app/cards/service.py - Card type rules
api/app/card_types/service.py - Fractional ordering
api/app/ordering.py
Persistence
- Database sessions
api/app/db.py - Board records
api/app/boards/models.py - Card records
api/app/cards/models.py - Column records
api/app/columns/models.py - Card type records
api/app/card_types/models.py - User and sessions
api/app/auth/models.py
External services
- PostgreSQL
- Google OAuth
Other components
- Board user
Connections 41
- Board user → SPA shell: uses
- SPA shell → Boards list: routes
web/src/App.tsx - SPA shell → Board workspace: routes
web/src/App.tsx - SPA shell → Archive view: routes
web/src/App.tsx - Board workspace → Board state: loads state
web/src/pages/BoardPage.tsx - Board workspace → Column and cards: renders
web/src/pages/BoardPage.tsx - Board workspace → Card types panel: renders
web/src/pages/BoardPage.tsx - Board workspace → Keyboard shortcuts: handles shortcuts
web/src/pages/BoardPage.tsx - Boards list → API client: requests
web/src/pages/BoardsPage.tsx - Board state → API client: requests
web/src/board/useBoard.ts - Column and cards → API client: requests
web/src/board/ColumnView.tsx - API client → FastAPI app: HTTP requests
- FastAPI app → Google sign-in: configures
api/app/main.py - FastAPI app → Request authentication: registers
api/app/main.py - FastAPI app → Board management: registers routes
api/app/main.py - Request authentication → Sessions and identity: resolves token
api/app/auth/dependencies.py - Sessions and identity → User and sessions: reads and writes
api/app/auth/sessions.py - Google sign-in → Google OAuth: OAuth exchange
- Board management → Board records: reads and writes
api/app/boards/service.py - Board management → Column records: seeds and reads
api/app/boards/service.py - Board management → Card type records: seeds and reads
api/app/boards/service.py - Board management → Card records: reads and deletes
api/app/boards/service.py - Column lifecycle → Column records: reads and writes
api/app/columns/service.py - Column lifecycle → Card records: moves or deletes
api/app/columns/service.py - Card lifecycle → Card records: reads and writes
api/app/cards/service.py - Card lifecycle → Column lifecycle: checks columns
api/app/cards/service.py - Card lifecycle → Card type rules: validates type
api/app/cards/service.py - Card type rules → Card type records: reads and writes
api/app/card_types/service.py - Card type rules → Card records: reassigns cards
api/app/card_types/service.py - Board management → Fractional ordering: generates sort keys
api/app/boards/service.py - Column lifecycle → Fractional ordering: generates sort keys
api/app/columns/service.py - Card lifecycle → Fractional ordering: generates sort keys
api/app/cards/service.py - FastAPI app → Database sessions: creates sessions
api/app/main.py - Database sessions → PostgreSQL: connects
- Sessions and identity → Database sessions: uses session
api/app/auth/sessions.py - Board records → Database sessions: maps records
api/app/boards/models.py - Card records → Database sessions: maps records
api/app/cards/models.py - Column records → Database sessions: maps records
api/app/columns/models.py - Card type records → Database sessions: maps records
api/app/card_types/models.py - User and sessions → Database sessions: maps records
api/app/auth/models.py - Archive view → API client: loads archive