Skip to main content

Workflow

Full Stack Development​

Run Everything​

From the project root:

docker-compose up

This starts:

  • PostgreSQL database (port 5018 external, 5432 internal)
  • Backend API (port 5017)
  • Frontend (served by backend on port 5017)

Access the app at http://localhost:5017.

Root Scripts​

CommandDescription
npm run install:allInstall deps for backend, frontend, docs
npm run buildBuild backend and frontend
npm run lintLint backend and frontend

Code Style​

Linting​

Both backend and frontend use ESLint:

# Backend
cd backend && npm run lint

# Frontend
cd frontend && npm run lint

# Both (from root)
npm run lint

TypeScript​

  • Strict mode enabled
  • Type definitions in types/ directories
  • Avoid any when possible

Formatting​

Consider using Prettier (not currently configured):

npm install --save-dev prettier

Contributing​

Workflow​

  1. Fork the repository
  2. Create a feature branch:
git checkout -b feature/my-feature
  1. Make your changes
  2. Test thoroughly:
npm test          # Backend tests
npm run lint      # Linting
  1. Commit with clear messages:
git commit -m "Add: Feature description"
  1. Push to your fork:
git push origin feature/my-feature
  1. Open a Pull Request

Commit Message Format​

Use conventional commits:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting)
  • refactor: Code refactoring
  • test: Test additions or changes
  • chore: Maintenance tasks

Pull Request Guidelines​

  • Clear description of changes
  • Reference related issues
  • Include tests for new features
  • Update documentation as needed
  • Ensure CI passes

Debugging​

Backend Debugging​

VS Code Launch Configuration:

{
  "type": "node",
  "request": "launch",
  "name": "Debug Backend",
  "runtimeExecutable": "npm",
  "runtimeArgs": ["run", "dev"],
  "cwd": "${workspaceFolder}/backend",
  "console": "integratedTerminal"
}

Logs:

# View backend logs
docker-compose logs -f backend

# View database logs
docker-compose logs -f database

Frontend Debugging​

  • Use React DevTools browser extension
  • Use browser developer tools
  • Check network tab for API calls
  • Check console for errors

Common Tasks​

Reset Database​

cd backend
npm run db:reset

Rebuild Docker Images​

docker-compose build --no-cache

Clean Node Modules​

# Backend
cd backend && rm -rf node_modules && npm install

# Frontend
cd frontend && rm -rf node_modules && npm install

View Database​

docker-compose exec database psql -U trajectory_user -d trajectory

Useful queries:

-- List all children
SELECT * FROM children;

-- Count visits
SELECT COUNT(*) FROM visits;

-- View migrations
SELECT * FROM migrations;

Resources​