Skip to main content

ØSTEN AI Development Guide

This guide provides instructions for setting up a local development environment for the ØSTEN AI platform.

The recommended method for local development is using Docker. This ensures a consistent and reproducible environment for all developers.

Prerequisites​

  • Docker Desktop
  • Git/GitHub Desktop
  • A code editor (e.g., VS Code)

Getting Started with Docker​

  1. Clone the repository

    git clone https://github.com/your-organization/osten-ai.git
    cd osten-ai

  2. Configure Environment Variables You will need to create .env files for secrets that should not be committed to version control.

    • Backend: Run cp backend/.env.example backend/.env (PowerShell: copy). Update DATABASE_URL if needed and fill in Firebase, Google Ads, and credential values.

    • Frontend: Run cp frontend/.env.local.example frontend/.env.local. Populate the Firebase client config and adjust NEXT_PUBLIC_API_URL if you're using the test stack.

  3. Run the Application Use Docker Compose to build and run the entire application stack (frontend, backend, and database).

    docker-compose up --build
    • The --build flag is only necessary the first time you run the command or after making changes to Dockerfiles or dependencies in package.json.
    • To run in detached mode, use docker-compose up -d.

    Once running, the services will be available at:

    • Frontend: http://localhost:3001
    • Backend: http://localhost:8080
    • Database: localhost:5432

  4. Stopping the Application To stop the services, press Ctrl+C in the terminal where docker-compose is running, or run:

    docker-compose down

Testing Environment (AI & Meridian disabled)​

Use this stack when you need an isolated environment for demos, QA, or multi-developer testing without relying on external AI infrastructure. The compose file disables AI routes and Meridian MMM processing via feature flags.

  1. Start the test stack

    docker-compose -f docker-compose.test.yml up --build

  2. Service endpoints

    • Frontend: http://localhost:3002
    • Backend: http://localhost:8081
    • Postgres: localhost:5433

  3. Feature flags

    • ENABLE_AI_FEATURES=false
    • ENABLE_MERIDIAN=false

The backend route handlers in backend/src/index.ts return a 503 response with a descriptive message whenever these features are disabled. Toggle the flags to true if you need to re-enable the endpoints locally.

  1. Stop the test stack 
    docker-compose -f docker-compose.test.yml down

Git Collaboration Workflow​

To ensure smooth collaboration and maintain code quality, we follow a feature-branch workflow.

  1. Stay Updated: Before starting new work, always pull the latest changes from the main branch.

    git checkout main
    git pull origin main

  2. Create a Feature Branch: Create a new branch for your feature or bugfix. Use a descriptive name, like feature/user-profile-page or bugfix/login-error.

    git checkout -b feature/your-feature-name

  3. Commit Your Work: Make your changes and commit them with clear, descriptive messages. Reference issue numbers if applicable.

    git add .
    git commit -m "feat: Add user profile page #123"

  4. Push Your Branch: Push your feature branch to the remote repository.

    git push -u origin feature/your-feature-name

  5. Open a Pull Request (PR): Go to the GitHub repository and open a pull request from your feature branch to the main branch. Provide a clear description of the changes and request a review from your collaborator.

  6. Review and Merge: After the PR is reviewed and approved, it can be merged into the main branch. Delete the feature branch after merging.

Coding Standards​

  • Use TypeScript for type safety.
  • Follow the existing ESLint and Prettier rules for consistent code style.
  • Write unit tests for new features and critical functionality.
  • Use Conventional Commits for your commit messages.

Deployment Automation​

  • Backend deployments to Google Cloud Run are handled by the GitHub Actions workflow at .github/workflows/deploy-backend.yml. Pushes to main that touch the backend folder (or manual runs) will:
    • Build the backend container image with Cloud Build.
    • Push the image to Artifact Registry.
    • Deploy the image to your Cloud Run service with ENABLE_AI_FEATURES and ENABLE_MERIDIAN enabled by default.
  • Ensure all Cloud Run secrets referenced by the workflow are configured in the repository settings before enabling the automation.