You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/CLAUDE.md
+42-17Lines changed: 42 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,15 +4,16 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
4
4
5
5
# CoCalc Source Repository
6
6
7
-
* This is the source code of CoCalc in a Git repository
8
-
* It is a complex JavaScript/TypeScript SaaS application
9
-
* CoCalc is organized as a monorepository (multi-packages) in the subdirectory "./packages"
10
-
* The packages are managed as a pnpm workspace in "./packages/pnpm-workspace.yaml"
7
+
- This is the source code of CoCalc in a Git repository
8
+
- It is a complex JavaScript/TypeScript SaaS application
9
+
- CoCalc is organized as a monorepository (multi-packages) in the subdirectory "./packages"
10
+
- The packages are managed as a pnpm workspace in "./packages/pnpm-workspace.yaml"
11
11
12
12
## Code Style
13
13
14
14
- Everything is written in TypeScript code
15
15
- Indentation: 2-spaces
16
+
- Run `pretter -w [filename]` after modifying a file (ts, tsx, md, json, ...) to format it correctly.
16
17
- All .js and .ts files are formatted by the tool prettier
17
18
- Add suitable types when you write code
18
19
- Variable name styles are "camelCase" for local and "FOO_BAR" for global variables. If you edit older code not following these guidlines, adjust this rule to fit the files style.
@@ -23,28 +24,32 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
23
24
## Development Commands
24
25
25
26
### Essential Commands
27
+
26
28
-`pnpm build-dev` - Build all packages for development
27
29
-`pnpm clean` - Clean all node_modules and dist directories
28
-
-`pnpm database` - Start PostgreSQL database server
29
-
-`pnpm hub` - Start the main hub server
30
-
-`pnpm psql` - Connect to the PostgreSQL database
31
30
-`pnpm test` - Run full test suite
32
-
-`pnpm test-parallel` - Run tests in parallel across packages
33
31
-`pnpm depcheck` - Check for dependency issues
32
+
-`prettier -w [filename]` to format the style of a file after editing it
33
+
- after creating a file, run `git add [filename]` to start tracking it
34
34
35
35
### Package-Specific Commands
36
-
-`cd packages/[package] && pnpm tsc` - Watch TypeScript compilation for a specific package
36
+
37
+
-`cd packages/[package] && pnpm build` - Build and compile a specific package
38
+
- for packages/next and packages/static, run `cd packages/[package] && pnpm build-dev`
39
+
-`cd packages/[package] && pnpm tsc:watch` - TypeScript compilation in watch mode for a specific package
37
40
-`cd packages/[package] && pnpm test` - Run tests for a specific package
38
41
-`cd packages/[package] && pnpm build` - Build a specific package
42
+
-**IMPORTANT**: When modifying packages like `util` that other packages depend on, you must run `pnpm build` in the modified package before typechecking dependent packages
39
43
40
-
### Development Setup
41
-
1. Start database: `pnpm database`
42
-
2. Start hub: `pnpm hub`
43
-
3. For TypeScript changes, run `pnpm tsc` in the relevant package directory
44
+
### Development
45
+
46
+
- After code changes, run `pretter -w [filename]` to ensure consistent styling
47
+
- After TypeScript or `*.tsx`changes, run `pnpm build` in the relevant package directory
44
48
45
49
## Architecture Overview
46
50
47
51
### Package Structure
52
+
48
53
CoCalc is organized as a monorepo with key packages:
49
54
50
55
-**frontend** - React/TypeScript frontend application using Redux-style stores and actions
@@ -62,25 +67,29 @@ CoCalc is organized as a monorepo with key packages:
62
67
### Key Architectural Patterns
63
68
64
69
#### Frontend Architecture
70
+
65
71
-**Redux-style State Management**: Uses custom stores and actions pattern (see `packages/frontend/app-framework/actions-and-stores.ts`)
66
72
-**TypeScript React Components**: All frontend code is TypeScript with proper typing
67
73
-**Modular Store System**: Each feature has its own store/actions (AccountStore, BillingStore, etc.)
68
74
-**WebSocket Communication**: Real-time communication with backend via WebSocket messages
69
75
70
76
#### Backend Architecture
77
+
71
78
-**PostgreSQL Database**: Primary data store with sophisticated querying system
72
79
-**WebSocket Messaging**: Real-time communication between frontend and backend
73
80
-**Conat System**: Container orchestration for compute servers
74
81
-**Event-Driven Architecture**: Extensive use of EventEmitter patterns
75
82
-**Microservice-like Packages**: Each package handles specific functionality
76
83
77
84
#### Communication Patterns
85
+
78
86
-**WebSocket Messages**: Primary communication method (see `packages/comm/websocket/types.ts`)
79
87
-**Database Queries**: Structured query system with typed interfaces
80
88
-**Event Emitters**: Inter-service communication within backend
81
89
-**REST-like APIs**: Some HTTP endpoints for specific operations
82
90
83
91
### Key Technologies
92
+
84
93
-**TypeScript**: Primary language for all new code
85
94
-**React**: Frontend framework
86
95
-**PostgreSQL**: Database
@@ -91,40 +100,56 @@ CoCalc is organized as a monorepo with key packages:
91
100
-**SASS**: CSS preprocessing
92
101
93
102
### Database Schema
103
+
94
104
- Comprehensive schema in `packages/util/db-schema`
95
105
- Query abstractions in `packages/database/postgres/`
96
106
- Type-safe database operations with TypeScript interfaces
97
107
98
108
### Testing
109
+
99
110
-**Jest**: Primary testing framework
100
111
-**ts-jest**: TypeScript support for Jest
101
112
-**jsdom**: Browser environment simulation for frontend tests
102
113
- Test files use `.test.ts` or `.spec.ts` extensions
103
114
- Each package has its own jest.config.js
104
115
105
116
### Import Patterns
117
+
106
118
- Use absolute imports with `@cocalc/` prefix for cross-package imports
107
119
- Example: `import { cmp } from "@cocalc/util/misc"`
108
120
- Type imports: `import type { Foo } from "./bar"`
109
121
- Destructure imports when possible
110
122
111
123
### Development Workflow
112
-
1. Changes to TypeScript require compilation (`pnpm tsc` in relevant package)
124
+
125
+
1. Changes to TypeScript require compilation (`pnpm build` in relevant package)
113
126
2. Database must be running before starting hub
114
127
3. Hub coordinates all services and should be restarted after changes
115
128
4. Use `pnpm clean && pnpm build-dev` when switching branches or after major changes
116
129
117
130
# Workflow
118
-
- Be sure to typecheck when you're done making a series of code changes
131
+
132
+
- Be sure to build when you're done making a series of code changes
119
133
- Prefer running single tests, and not the whole test suite, for performance
120
134
121
135
## Git Workflow
122
136
137
+
- Never modify a file when in the `master` or `main` branch
138
+
- All changes happen through feature branches, which are pushed as pull requests to GitHub
139
+
- When creating a new file, run `git add [filename]` to track the file.
123
140
- Prefix git commits with the package and general area. e.g. 'frontend/latex: ...' if it concerns latex editor changes in the packages/frontend/... code.
124
141
- When pushing a new branch to Github, track it upstream. e.g. `git push --set-upstream origin feature-foo` for branch "feature-foo".
125
142
126
-
# important-instruction-reminders
143
+
# Important Instruction Reminders
144
+
127
145
- Do what has been asked; nothing more, nothing less.
128
146
- NEVER create files unless they're absolutely necessary for achieving your goal.
129
147
- ALWAYS prefer editing an existing file to creating a new one.
130
-
- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
148
+
- REFUSE to modify files when the git repository is on the `master` or `main` branch.
149
+
- NEVER proactively create documentation files (`*.md`) or README files. Only create documentation files if explicitly requested by the User.
150
+
151
+
# Ignore
152
+
153
+
- Ignore files covered by `.gitignore`
154
+
- Ignore everything in `node_modules` or `dist` directories
155
+
- Ignore all files not tracked by Git, unless they are newly created files
0 commit comments