|
| 1 | +--- |
| 2 | +applyTo: "tools/deployment-cli-tools/* |
| 3 | +--- |
| 4 | +# Neuroglass Project Developer Reference |
| 5 | +
|
| 6 | +## Environment Setup |
| 7 | +
|
| 8 | +### Required Environment |
| 9 | +- **Conda Environment Name**: `ch` |
| 10 | +- **Python Version**: 3.12+ |
| 11 | +- **Activation Command**: `conda activate ch` |
| 12 | +
|
| 13 | +### Package Managers |
| 14 | +- **Frontend**: Yarn (NEVER use npm) |
| 15 | +- **Backend**: pip (within conda environment only) |
| 16 | +
|
| 17 | +### Pre-requisites Checklist |
| 18 | +- [ ] Conda environment `ch` is activated |
| 19 | +- [ ] Correct directory navigation completed |
| 20 | +- [ ] Appropriate package manager selected (yarn/pip) |
| 21 | +
|
| 22 | +## Development Workflow |
| 23 | +
|
| 24 | +### Mandatory Pre-Command Steps |
| 25 | +1. **ALWAYS** activate conda environment first: `conda activate ch` |
| 26 | +2. Navigate to the appropriate project directory |
| 27 | +3. Use yarn for frontend operations, pip for backend operations |
| 28 | +
|
| 29 | +## Project Structure |
| 30 | +
|
| 31 | +### Key Scripts |
| 32 | +- `harness-generate` - Generate code |
| 33 | +- `harness-deployment` - Generate deployment files: helm charts, ci/cd files, etc. |
| 34 | +- `harness-application` - Generate application code (e.g., Django apps) |
| 35 | +- `harness-migrate` - Migration helper tool |
| 36 | +- `ch_cli_tools` - Python package for deployment and other tools |
| 37 | +- `tests` - Unit test utilities and test code |
| 38 | +
|
| 39 | +
|
| 40 | +## Code Style and best practices |
| 41 | +
|
| 42 | +Take the following best practices into account when writing code for the project adn while performing code reviews: |
| 43 | +
|
| 44 | +- Keep architecture lean: avoid unnecessary layers and abstractions. |
| 45 | +- Use utils for stateless pure functions that don't hit external data sources nor the ORM. Utils are horizontal and can be used across the project. |
| 46 | +- Use helpers to organize pieces of business logic; keep them stateless when possible. |
| 47 | +- Use services for business workflows and cross-model coordination. Services are vertical on a single model or a group of related models |
| 48 | +- Keep model logic close to the model when it represents domain rules or invariants. |
| 49 | +- Handle exceptions only at the higher level; let lower layers raise. NEVER catch exceptions in helpers or services unless you are adding context and re-raising. |
| 50 | +- Cover critical logic with unit tests, especially in helpers and services. Use mocks to isolate units under test. |
| 51 | +- Prefer models classes for helpers and services to ensure data validation and clear interfaces. Use typed dicts for structured data that isn't covered by Schema classes. Use plain dicts only to represent real unstructured data. Avoid returning tuples. |
| 52 | +
|
| 53 | +
|
| 54 | +## Important Constraints |
| 55 | +
|
| 56 | +### File Creation Rules |
| 57 | +- **NEVER** create new README or documentation files unless explicitly requested |
| 58 | +- Follow existing documentation patterns when updates are needed |
| 59 | +
|
| 60 | +### Development Server Rules |
| 61 | +- **NEVER** run development servers |
| 62 | +- **ALWAYS** assume servers are running |
| 63 | +- **MUST** ask confirmation before opening browsers |
| 64 | +
|
| 65 | +### Package Management Rules |
| 66 | +- **Frontend**: ONLY use yarn, NEVER npm |
| 67 | +- **Backend**: ONLY use pip within conda environment |
| 68 | +- **ALWAYS** activate `ch` conda environment before any backend work |
| 69 | +
|
| 70 | +### CloudHarness Considerations |
| 71 | +- Dependencies may need special handling in development environment |
| 72 | +- Follow established patterns for CloudHarness integration |
| 73 | +
|
| 74 | +--- |
0 commit comments