Getting Started
Fork and clone
# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/YOUR_USERNAME/latentgeo.git
cd latentgeo
Set up development environment
Create a feature branch
git checkout -b feature/your-feature-name
feature/ - New featuresfix/ - Bug fixesrefactor/ - Code refactoringdocs/ - Documentation updatestest/ - Test additions or fixes
Code Quality Standards
Backend (Python)
Run before every commit:
# Auto-format code
python -m black backend
python -m isort backend
# Lint
python -m ruff check backend/app backend/tests
# Type check
python -m mypy backend/app --ignore-missing-imports
Consider setting up pre-commit hooks to automate these checks.
Code Style
- Follow PEP 8 conventions
- Use type hints for function signatures
- Maximum line length: 100 characters (Black default)
- Use descriptive variable names
Example:
from typing import Optional
from sqlalchemy.orm import Session
from app.models import Audit
class AuditService:
@staticmethod
def get_audit(db: Session, audit_id: int) -> Optional[Audit]:
"""Retrieve audit by ID."""
return db.query(Audit).filter(Audit.id == audit_id).first()
Security Guidelines
- Never commit secrets (.env files, API keys, credentials)
- Use environment variables for configuration
- Validate all user inputs
- Always check ownership before allowing access to resources
# Bad - No ownership check
def delete_audit(db: Session, audit_id: int):
audit = db.query(Audit).filter(Audit.id == audit_id).first()
db.delete(audit)
# Good - Verify ownership
def delete_audit(db: Session, audit_id: int, user_email: str):
audit = db.query(Audit).filter(
Audit.id == audit_id,
Audit.user_email == user_email
).first()
if not audit:
raise HTTPException(status_code=404)
db.delete(audit)
Frontend (TypeScript/React)
# Auto-format
prettier --write frontend/
# Lint
pnpm --dir frontend lint
# Type check
pnpm --dir frontend run type-check
Code Style
- Use functional components with hooks
- Prefer TypeScript strict mode
- Use
const over let when possible
- Destructure props in component signatures
Example:
import { Button } from '@/components/ui/button';
interface AuditCardProps {
title: string;
status: 'pending' | 'running' | 'completed';
onView: () => void;
}
export function AuditCard({ title, status, onView }: AuditCardProps) {
return (
<div className="rounded-lg border p-4">
<h3 className="font-semibold">{title}</h3>
<p className="text-sm text-muted-foreground">{status}</p>
<Button onClick={onView}>View Details</Button>
</div>
);
}
Component Organization
components/
├── ui/ # Radix UI primitives (button, dialog, etc.)
├── providers/ # Context providers
├── [feature].tsx # Feature-specific components
Testing Requirements
All PRs must include tests for new functionality.
Backend Tests
import pytest
from app.services.audit_service import AuditService
from app.schemas import AuditCreate
def test_create_audit(db_session):
"""Test audit creation."""
audit_data = AuditCreate(
url="https://example.com",
user_email="[email protected]"
)
audit = AuditService.create_audit(db_session, audit_data)
assert audit.id is not None
assert audit.url == "https://example.com"
assert audit.status == "pending"
Frontend Tests
import { describe, it, expect } from 'vitest';
import { render, screen, fireEvent } from '@testing-library/react';
import { AuditCard } from './AuditCard';
describe('AuditCard', () => {
it('calls onView when button clicked', () => {
const onView = vi.fn();
render(
<AuditCard
title="Test Audit"
status="completed"
onView={onView}
/>
);
fireEvent.click(screen.getByText('View Details'));
expect(onView).toHaveBeenCalled();
});
});
Running Tests
Run the full suite before submitting:
# Backend
pytest -q backend/tests -m "not integration and not live"
# Frontend
pnpm --dir frontend test:ci
# Security regression
pytest -q backend/tests/test_security_remediation.py
Git Workflow
Commit Messages
Follow conventional commit format:
<type>(<scope>): <subject>
<body>
<footer>
feat: New featurefix: Bug fixrefactor: Code refactoringtest: Test additionsdocs: Documentationchore: Build/tooling changes
Examples:
feat(audit): add PageSpeed integration
fix(auth): resolve token refresh race condition
refactor(pipeline): extract LLM logic into service
docs(setup): update Docker Compose instructions
test(security): add ownership validation tests
Good commit: feat(geo): add keyword gap analysisBad commit: updated stuff
Making Changes
Make your changes
Follow code quality standards and test your changes locally.
Run quality checks
# Backend
python -m black backend
python -m ruff check backend/app backend/tests
pytest -q backend/tests -m "not integration and not live"
# Frontend
pnpm --dir frontend lint
pnpm --dir frontend test:ci
pnpm --dir frontend build
Commit changes
git add .
git commit -m "feat(scope): descriptive message"
Push to your fork
git push origin feature/your-feature-name
Pull Request Process
Creating a PR
Open pull request on GitHub
Navigate to the main repository and create a PR from your fork.
Fill out PR template
Provide:
- Description: What does this PR do?
- Motivation: Why is this change needed?
- Testing: How was it tested?
- Screenshots: For UI changes
Link related issues
Reference issues using keywords:Fixes #123
Closes #456
Related to #789
PR Template
## Description
Brief description of changes.
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated
- [ ] No new warnings generated
Review Process
- Automated checks: CI pipeline runs linting, tests, and builds
- Code review: Maintainers review code quality and design
- Testing: Changes are tested in staging environment
- Approval: At least one maintainer approval required
- Merge: Squash and merge to main branch
Maintainers may request changes or ask questions. Respond promptly and update your PR.
API Changes
When modifying backend APIs:
Update schemas
Modify Pydantic schemas in backend/app/schemas/
Update routes
Modify FastAPI routes in backend/app/api/routes/
Regenerate frontend types
pnpm --dir frontend run api:generate-types
Update frontend clients
Modify API calls in frontend/lib/api-client/
Test contract
pytest backend/tests/test_api_contract.py
pnpm --dir frontend run type-check
API changes may require frontend updates. Coordinate with frontend maintainers.
Documentation
Update documentation for:
- New features or APIs
- Changed configuration options
- New environment variables
- Migration guides for breaking changes
# Add documentation in docs/
touch docs/features/new-feature.mdx
Getting Help
GitHub Discussions
Ask questions and discuss ideas
Discord Community
Real-time chat with contributors
Issue Tracker
Report bugs or request features
Documentation
Browse guides and API reference
Code of Conduct
Be respectful, inclusive, and professional. We welcome contributions from everyone.
Next Steps
Local Setup
Set up your development environment
Testing Guide
Learn how to test your changes
Backend Services
Understand the service architecture
Frontend Components
Build with our component library