Skip to content

Commit f55851e

Browse files
bidyashishbidyashish
authored
Merge pull request #60 from bidyashish/work1
feat: add project documentation, build automation, new user data, and…
2 parents 8797d0f + c0b1a11 commit f55851e

3 files changed

Lines changed: 354 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,26 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
66

77
`AGENTS.md` at the repo root is the canonical agent brief (project summary, coding standards, security rules, deployment, backlog). Read it first. The notes below focus on commands, current architecture reality, and gotchas — they do **not** repeat what's in `AGENTS.md`.
88

9+
`CONTRIBUTING.md` (root) is the human-oriented onboarding doc - file-location conventions, where new code goes, hot-spot list. Cross-reference it when adding any non-trivial module so the layout stays consistent.
10+
11+
## Tooling (use this, not the individual commands below)
12+
13+
A root `Makefile` bundles every workflow. Prefer these targets over remembering tool flags - they mirror CI exactly:
14+
15+
```bash
16+
make help # list every target
17+
make install # first-time: venv + npm ci + pre-commit install
18+
make dev # backend (:8001) + frontend (:3121) together
19+
make check # ruff + ruff format --check + tsc + oxlint + oxfmt --check (CI mirror)
20+
make format # ruff format + oxfmt (auto-fix)
21+
make pre-commit # format then check - run before every commit
22+
make test # pytest (CI doesn't run tests, but the suite is fast)
23+
make ci # check + test
24+
make clean # caches and dist/
25+
```
26+
27+
`make pre-commit` is the safe path. CI runs only the `--check` modes; if format-check fails on CI it means you skipped `make format` (or `make pre-commit`) locally. Pre-commit hooks (see `.pre-commit-config.yaml`) catch the same thing on `git commit` once `make install-hooks` has been run.
28+
929
**Known drift from `AGENTS.md`**: `AGENTS.md` still describes the frontend as "Next.js 15 with App Router" and the backend using MongoDB. Neither is current. The frontend is **Vite + React 19 + TypeScript** (not CRA, not Next.js, not craco — all removed). The backend no longer uses MongoDB at all (removed April 2026 — the MongoDB server-selection timeout was the source of a 30 s request-latency bug). Backend entry is `server:app` (`backend/server.py`). Trust the code, not `AGENTS.md`, on these points.
1030

1131
## Commands

‎CONTRIBUTING.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Contributing
2+
3+
A short guide to keep changes consistent and CI green. The repo is small, so
4+
the only hard rule is the title: **green CI, clear file location, no surprise
5+
abstractions.**
6+
7+
---
8+
9+
## Quick start
10+
11+
```bash
12+
make install # once: venv, npm deps, pre-commit hooks
13+
make dev # runs backend (:8001) and frontend (:3121) together
14+
make check # mirrors CI - run before pushing
15+
make pre-commit # format + check (the safe way to ship)
16+
make help # lists every target
17+
```
18+
19+
The `Makefile` is the source of truth for commands. If a step is missing
20+
from the Makefile, add it there before adding it to your shell history.
21+
22+
---
23+
24+
## File layout
25+
26+
### Backend (`backend/`, flat Python package)
27+
28+
```
29+
backend/
30+
├── server.py FastAPI app, routes, request/response models.
31+
├── calculator.py compute_chart(): full birth-chart pipeline.
32+
├── transits.py Sign / nakshatra / retrograde event scanner.
33+
├── muhurta.py Auspicious-window finder.
34+
├── advanced_panchang.py Daily Drik Panchang (tithi, nakshatra, yoga ...).
35+
├── panchang_extras.py Layered yogas on top of advanced_panchang.
36+
├── panchang_constants.py Tables for the panchang modules.
37+
├── ayanamsa.py Ayanamsa option table + setter.
38+
├── constants.py Sign / nakshatra / tithi / vara names.
39+
├── vargas.py D1-D60 divisional chart math.
40+
├── dasha_extras.py Antardasha / Pratyantar sub-period computation.
41+
├── drishti.py Vedic aspect calculator.
42+
├── relationships.py Natural / temporal / 5-fold friendship matrices.
43+
├── jaimini.py Chara karakas + Karakamsa / Swamsa charts.
44+
├── kalsarpa.py Kalsarpa Yoga detection.
45+
├── mangal.py Mangal Dosha analysis.
46+
├── sade_sati.py Saturn-from-Moon 120-year transit table.
47+
├── gowri_panchang.py Tamil/Telugu Gowri Panchangam.
48+
├── hora.py Planetary Hora hours.
49+
├── nalla_neram.py Tamil Nalla Neram windows.
50+
├── tamil_calendar.py Tamil calendar (year, month, weekday).
51+
├── tyajyam.py Inauspicious time periods.
52+
├── pdf/ PDF report renderer (its own subpackage).
53+
├── ephe/ Swiss Ephemeris data files. NEVER move or delete.
54+
└── tests/ pytest suites + conftest.
55+
```
56+
57+
**Where does new backend code go?**
58+
59+
- A new astronomical calculation (varga variant, dosha analysis): new
60+
top-level `backend/<name>.py`. Match the existing one-word naming.
61+
- A new panchang section: add to `advanced_panchang.py` if it shares the
62+
daily sunrise/sunset machinery, otherwise its own module.
63+
- A new API route: in `server.py`. Keep `server.py` thin - it should
64+
delegate calculation to a module.
65+
- Constants and lookup tables: prefer `constants.py` (chart names) or
66+
`panchang_constants.py` (panchang tables).
67+
68+
**Style:** `make format-backend` (ruff format) handles every choice. No
69+
manual style decisions.
70+
71+
### Frontend (`frontend/src/`, feature-folder layout)
72+
73+
```
74+
src/
75+
├── App.tsx Shell: TopBar, route switcher, Footer.
76+
├── main.tsx Entry: I18nProvider + StrictMode.
77+
├── index.css Tailwind globals + token bridge.
78+
│
79+
├── pages/ One file per top-level route.
80+
│ ├── KundaliPage.tsx
81+
│ ├── PanchangPage.tsx
82+
│ ├── MuhurtaPage.tsx
83+
│ ├── TransitsPage.tsx
84+
│ └── ...
85+
│
86+
├── components/ UI grouped by the page that owns it.
87+
│ ├── common/ Used by 2+ pages (CitySearch, MandalaLoader).
88+
│ ├── shell/ TopBar, Footer, NotificationBanner.
89+
│ ├── ui/ Generic primitives (DatePicker, Switch).
90+
│ ├── kundali/ Kundali-page-specific (Charts, PlanetsTable).
91+
│ ├── panchang/ Panchang-page-specific (Section, TimeBand).
92+
│ └── transits/ Transit-page-specific (TransitTimeline).
93+
│
94+
├── lib/ Pure utilities. No React, no JSX.
95+
│ ├── api.ts Typed fetch wrappers for every backend route.
96+
│ ├── format.ts Date / time / number formatters.
97+
│ ├── planets.ts Planet abbr -> colour / long-name tables.
98+
│ ├── seo.ts applySeo() for per-route title/canonical.
99+
│ └── ...
100+
│
101+
├── i18n/ Internationalisation.
102+
│ ├── index.tsx LANGUAGES, I18nProvider, useI18n.
103+
│ ├── astro.ts Planet/sign/nakshatra translation dictionaries.
104+
│ └── locales/ UI-string dictionaries per locale.
105+
│
106+
└── types/api.ts TypeScript shapes for backend responses.
107+
```
108+
109+
**Where does new frontend code go?**
110+
111+
- New top-level route: page file in `pages/` + entry in `App.tsx`
112+
(`View` union, `VIEW_PATH`, `SEO_BY_VIEW`, `viewFromPath`) + tab in
113+
`components/shell/TopBar.tsx` + nav-label key in
114+
`i18n/locales/en.ts` (other locales fall back to English).
115+
- New component used by one page: `components/<page>/<Name>.tsx`.
116+
- New component used by two or more pages: promote to `components/common/`.
117+
- New API call: typed wrapper in `lib/api.ts` + matching type in
118+
`types/api.ts`.
119+
- New translatable string: English in `i18n/locales/en.ts` (mandatory);
120+
other locales optional - they fall back to English automatically. Astro
121+
names (planet / sign / nakshatra) go in `i18n/astro.ts` instead.
122+
123+
**Path alias:** `@/...` resolves to `src/...`. Always use it. Never
124+
`../../components/...`.
125+
126+
**Style:** `make format-frontend` (oxfmt) handles every choice.
127+
128+
---
129+
130+
## Conventions
131+
132+
### Naming
133+
134+
- **Files:** snake_case for Python, kebab-case isn't used in this repo;
135+
TSX files are PascalCase for components (`TransitTimeline.tsx`) and
136+
camelCase for non-component modules (`urlState.ts`).
137+
- **Tests:** mirror the module they cover: `transits.py` ->
138+
`tests/test_transits.py`.
139+
140+
### Imports
141+
142+
- Backend: prefer absolute imports (`from calculator import compute_chart`).
143+
`conftest.py` puts `backend/` on `sys.path` for tests.
144+
- Frontend: always use `@/` alias.
145+
146+
### Types
147+
148+
- Backend uses Pydantic models in `server.py` for request bodies.
149+
- Frontend mirrors every response shape in `types/api.ts`. Run
150+
`make check-frontend` to catch shape drift.
151+
152+
### Comments
153+
154+
CLAUDE.md is authoritative here. Short version:
155+
156+
- Default to no comments. Names should carry the meaning.
157+
- Add a comment only for the non-obvious **why**: a hidden constraint, a
158+
workaround for a specific bug, behaviour that would surprise a reader.
159+
- No em dashes (use `-`). UI/i18n strings stay plain ASCII in English.
160+
Hindi / Tamil / Bengali / etc. use their native script.
161+
162+
---
163+
164+
## Workflow
165+
166+
```bash
167+
git checkout -b feat/whatever
168+
# ... edit ...
169+
make pre-commit # format + verify; same gates as CI
170+
git add ...
171+
git commit -m "feat: short message"
172+
git push -u origin feat/whatever
173+
gh pr create
174+
```
175+
176+
The `pre-commit-config.yaml` hooks fire automatically on `git commit` once
177+
`make install-hooks` has been run. They run ruff + oxfmt + oxlint - the
178+
same tools `make check` runs in `--check` mode.
179+
180+
### Before opening a PR
181+
182+
1. `make pre-commit` passes (mirrors CI gates).
183+
2. `make test` passes (CI doesn't run tests today, but the suite is
184+
fast and catches a lot).
185+
3. Manual UI test if you touched anything visual. Memory note:
186+
visual changes need to be confirmed in a browser before shipping.
187+
188+
---
189+
190+
## Industry-standard practices we've adopted
191+
192+
| Practice | Where | Why |
193+
|---|---|---|
194+
| **Pre-commit hooks** | `.pre-commit-config.yaml` | Catch format issues before CI does. |
195+
| **Single dev entrypoint** | `Makefile` | New contributors run one command, not five. |
196+
| **Editor consistency** | `.editorconfig` | Same indentation/EOLs across editors. |
197+
| **Path aliases** | `@/` in `tsconfig.json`, `vite.config.ts` | Refactors stop breaking on file moves. |
198+
| **Feature folders** | `components/{kundali,panchang,...}/` | Keep the change-blast-radius small. |
199+
| **CI mirror locally** | `make check` | "Works on my machine" goes away. |
200+
| **Typed API boundary** | `types/api.ts` + Pydantic in `server.py` | Schema drift caught at build time. |
201+
202+
---
203+
204+
## Known hot spots
205+
206+
These files are large enough that a future split would help, but the
207+
mechanical risk is non-trivial. Listed so they get prioritised when
208+
touched substantially:
209+
210+
| File | Lines | Suggested split |
211+
|---|---|---|
212+
| `frontend/src/i18n/astro.ts` | 2161 | Each locale dict (HI/TA/...) into its own file under `i18n/astro/`, keep `index.ts` for the lookup helpers. |
213+
| `backend/advanced_panchang.py` | 1255 | Group by panchang section: tithi/nak/yoga/karana detectors separated from sunrise/sunset machinery. |
214+
| `frontend/src/pages/PanchangPage.tsx` | 1161 | Extract each `<Section>` block into its own component under `components/panchang/`. |
215+
216+
A split is only worth it if it reduces "where do I edit?" friction. Don't
217+
split for line-count alone.

‎Makefile‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Vedic Panchanga developer Makefile.
2+
#
3+
# One command per common operation. Targets named after intent, not tools,
4+
# so `make check` keeps working if we swap ruff for pyright or oxlint for
5+
# eslint in the future.
6+
#
7+
# Mirrors .github/workflows/ci.yml exactly so `make ci` locally is a
8+
# faithful preview of what the pull-request gates will run.
9+
10+
# ---- Configuration --------------------------------------------------------
11+
12+
PY := backend/venv/bin/python
13+
PIP := backend/venv/bin/pip
14+
PYTEST := backend/venv/bin/pytest
15+
RUFF := backend/venv/bin/ruff
16+
UVICORN := backend/venv/bin/uvicorn
17+
18+
NPM := npm --prefix frontend
19+
20+
# ---- Discoverability ------------------------------------------------------
21+
22+
.PHONY: help
23+
help: ## Show this help (default target).
24+
@awk 'BEGIN {FS = ":.*##"; printf "\nUsage: make \033[36m<target>\033[0m\n\nTargets:\n"} \
25+
/^[a-zA-Z_-]+:.*##/ { printf " \033[36m%-18s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
26+
27+
.DEFAULT_GOAL := help
28+
29+
# ---- One-time setup -------------------------------------------------------
30+
31+
.PHONY: install
32+
install: install-backend install-frontend install-hooks ## First-time setup: venv, npm deps, git hooks.
33+
34+
.PHONY: install-backend
35+
install-backend: ## Create backend venv and install Python deps.
36+
test -d backend/venv || python3 -m venv backend/venv
37+
$(PIP) install -r backend/requirements.txt
38+
39+
.PHONY: install-frontend
40+
install-frontend: ## Install frontend npm deps.
41+
$(NPM) ci
42+
43+
.PHONY: install-hooks
44+
install-hooks: ## Install pre-commit hooks so format issues never reach CI.
45+
@if command -v pre-commit >/dev/null 2>&1; then \
46+
pre-commit install; \
47+
else \
48+
echo "pre-commit not on PATH. Install with: pipx install pre-commit"; \
49+
echo "or: pip install --user pre-commit"; \
50+
fi
51+
52+
# ---- Development servers --------------------------------------------------
53+
54+
.PHONY: backend
55+
backend: ## Run the FastAPI dev server on 127.0.0.1:8001.
56+
cd backend && venv/bin/uvicorn server:app --host 127.0.0.1 --port 8001 --reload
57+
58+
.PHONY: frontend
59+
frontend: ## Run the Vite dev server on :3121.
60+
$(NPM) run dev
61+
62+
.PHONY: dev
63+
dev: ## Run backend and frontend together (foreground; Ctrl-C stops both).
64+
@$(MAKE) -j2 backend frontend
65+
66+
# ---- Tests ----------------------------------------------------------------
67+
68+
.PHONY: test
69+
test: test-backend ## Run all tests (currently backend only; no FE test runner yet).
70+
71+
.PHONY: test-backend
72+
test-backend: ## Run pytest with default options.
73+
cd backend && venv/bin/pytest tests/ -v
74+
75+
# ---- Format / lint --------------------------------------------------------
76+
77+
.PHONY: format
78+
format: format-backend format-frontend ## Auto-fix all formatting in both languages.
79+
80+
.PHONY: format-backend
81+
format-backend: ## Write ruff formatting to all backend Python files.
82+
$(RUFF) format backend
83+
84+
.PHONY: format-frontend
85+
format-frontend: ## Write oxfmt formatting to all frontend sources.
86+
$(NPM) run format
87+
88+
.PHONY: check
89+
check: check-backend check-frontend ## Run all CI gates locally (lint + format-check + typecheck).
90+
91+
.PHONY: check-backend
92+
check-backend: ## Mirror CI's backend job: ruff lint + ruff format --check.
93+
$(RUFF) check backend
94+
$(RUFF) format --check backend
95+
96+
.PHONY: check-frontend
97+
check-frontend: ## Mirror CI's frontend job: tsc + oxlint + oxfmt --check.
98+
cd frontend && npx tsc --noEmit
99+
$(NPM) run lint
100+
$(NPM) run format:check
101+
102+
# ---- Convenience composites ----------------------------------------------
103+
104+
.PHONY: pre-commit
105+
pre-commit: format check ## Format then verify. Run before every commit.
106+
107+
.PHONY: ci
108+
ci: check test ## Full local CI preview: every gate + tests.
109+
110+
# ---- Hygiene --------------------------------------------------------------
111+
112+
.PHONY: clean
113+
clean: ## Remove build artefacts and caches (keeps venv and node_modules).
114+
rm -rf frontend/dist
115+
find backend -type d -name __pycache__ -prune -exec rm -rf {} +
116+
find backend -type d -name .pytest_cache -prune -exec rm -rf {} +
117+
rm -rf backend/.ruff_cache .ruff_cache

0 commit comments

Comments
 (0)