CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Repository Overview
6 
7This is the "Project Shisha" monorepo structure for Bun/Node applications with Docker, Ansible, and NX build orchestration. The repository contains:
8 
9### Applications
101. `apps/fuel-advisor-bot/` - Telegram bot for fuel price recommendations
112. `apps/tablo-crawler/` - Crawler application
12 
13### Shared Packages
143. `packages/shared-lib/` - Shared utilities and helpers
154. `packages/shared-config/` - Shared ESLint and TypeScript configurations
16 
17## NX Build Orchestration
18 
19This project uses **NX** for build orchestration, caching, and affected project detection. NX works alongside Bun workspaces.
20 
21### Key NX Commands
22 
23```bash
24# Build all projects (respects dependency order)
25npm run nx:build
26 
27# Build only affected projects (changes since main)
28npm run nx:build:affected
29 
30# Test all/affected projects
31npm run nx:test
32npm run nx:test:affected
33 
34# Lint all/affected projects
35npm run nx:lint
36npm run nx:lint:affected
37 
38# TypeScript check all/affected projects
39npm run nx:typecheck
40npm run nx:typecheck:affected
41 
42# Visualize project graph
43npm run nx:graph
44 
45# List all projects
46npm run nx:show:projects
47 
48# Clear cache
49npm run nx:reset
50```
51 
52### Project Dependencies
53 
54```
55shared-config → shared-lib → fuel-advisor-bot
56                            → tablo-crawler
57```
58 
59When using `nx affected`, NX automatically determines which projects need rebuilding based on source changes and their dependencies.
60 
61## Development Setup
62 
63### Prerequisites
64 
65- Bun 1.0+ or Node.js 18+
66- NX CLI (installed as dev dependency)
67 
68### Quick Start
69 
70```bash
71# Install dependencies
72bun install
73 
74# Run development mode
75bun run dev:fuel-advisor-bot
76bun run dev:tablo-crawler
77 
78# Build all projects with NX (caches results)
79npm run nx:build
80 
81# Build only changed projects
82npm run nx:build:affected
83```
84 
85## Project Structure
86 
87```
88project-shisha/
89├── nx.json                    # NX workspace configuration
90├── apps/
91│   ├── fuel-advisor-bot/
92│   │   ├── project.json       # NX project config
93│   │   └── ...
94│   └── tablo-crawler/
95│       ├── project.json       # NX project config
96│       └── ...
97├── packages/
98│   ├── shared-lib/
99│   │   └── project.json       # Library project config
100│   └── shared-config/
101│       └── project.json       # Config library project
102└── .nx/                       # Shared NX configurations
103```
104 
105## Key Technologies
106 
107- **Bun** - JavaScript runtime and package manager
108- **NX** - Build orchestration and caching
109- **Node.js** - Runtime environment
110- **Docker** - Containerization
111- **Ansible** - Deployment automation
112- **Watchtower** - Container update monitoring
113 
114## Deployment
115 
116Both applications follow a consistent deployment pattern:
117 
1181. Update `deploy.vars.yml` with configuration
1192. Build with NX (uses cache):
120```bash
121   npm run nx:build:affected
122```
1233. Deploy using Ansible:
124```bash
125   ansible-playbook -i ansible/inventories/production/hosts.ini ansible/playbooks/deploy-app.yml
126```
127 
128## Environment Variables
129 
130Each application has its own `.env.example` file that should be copied to `.env` and updated with appropriate values.
131 
132## Testing
133 
134```bash
135# Test all projects (cached)
136npm run nx:test
137 
138# Test only affected projects
139npm run nx:test:affected
140 
141# Test specific project
142npx nx test fuel-advisor-bot
143```
144 
145## Remote Caching (Optional)
146 
147To enable remote caching with Nx Cloud:
148 
1491. Connect: `npx nx connect-to-nx-cloud`
1502. Set `NX_CLOUD_ACCESS_TOKEN` in GitHub Actions
151 
152This allows build cache to be shared across machines and CI pipelines.
153