File size: 2,538 Bytes
9fe4fad | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | ---
title: Development Guide
summary: Local workflow for code, docs, tests, notebooks, and frontend changes.
---
# Development Guide
This page is the maintainer-facing companion to the product docs.
## Repo Layout
| Path | Purpose |
|------|---------|
| `src/TerraFin/data/` | Data providers, normalization, and output types |
| `src/TerraFin/analytics/` | Indicators, DCF, risk, options, portfolio, and simulation helpers |
| `src/TerraFin/interface/` | FastAPI app, page routes, and frontend |
| `src/TerraFin/agent/` | External-agent client, hosted runtime, model runtime, and tools |
| `docs/` | Formal documentation site source |
| `tests/` | Automated regression coverage |
| `notebooks/` | Manual and demo notebooks only |
## Local Setup
```bash
pip install -e ".[dev]"
```
Add extras when needed:
```bash
pip install -e ".[db]"
pip install -e ".[notebooks]"
pip install -e ".[docs]"
```
## Tests
Core Python tests:
```bash
pytest
```
Agent-focused slice:
```bash
pytest tests/agent tests/interface/test_agent_api.py
```
Packaging smoke:
```bash
python -m build
python scripts/package_smoke.py
```
## Frontend
The frontend lives under `src/TerraFin/interface/frontend/`.
Typical commands:
```bash
npm install
npm run build
```
When you touch page-specific agent context, DCF workbenches, or the hosted
assistant widget, verify both desktop and mobile flows.
## Docs Site
TerraFin now ships a formal static docs site using MkDocs Material.
Preview locally:
```bash
pip install -e ".[docs]"
mkdocs serve
```
Build locally:
```bash
mkdocs build --strict
```
GitHub Pages deployment is defined in `.github/workflows/docs-pages.yml`.
## Notebook Rules
Notebooks are for human-guided exploration, not automated tests.
- keep notebooks under `notebooks/`
- do not use a `test_` prefix for notebook filenames
- promote stable notebook logic into `tests/test_*.py` if it becomes regression-critical
Detailed notebook guidance lives in [Notebooks](notebooks.md).
## External Artifacts
Some code-adjacent references remain useful even though they are not formal
docs pages:
- analytics implementation notes:
[src/TerraFin/analytics/analysis/README.md](https://github.com/KiUngSong/TerraFin/blob/main/src/TerraFin/analytics/analysis/README.md)
- shipped TerraFin skill:
[skills/terrafin/SKILL.md](https://github.com/KiUngSong/TerraFin/blob/main/skills/terrafin/SKILL.md)
## Related Docs
- [Feature Integration](feature-integration.md)
- [Analytics Notes](analytics-notes.md)
- [Notebooks](notebooks.md)
|