Staffjoy Suite (V1) Documentation

The project uses Google YAPF to enforce PEP-8 compliance. You must run the formatter before committing code, or the build will fail.

To format your code:

make fmt

To disable formatting for specific blocks of code, use the following comments:

# yapf: disable
FOO = { ... }
# yapf: enable

The /api/v2/internal/cron/ endpoint must be triggered every 60 seconds to maintain system operations. You can use a tool like Jenkins or a dedicated cron microservice to call this endpoint using HTTP Basic Auth.

Note: When using curl, the trailing colon after the API key is required to indicate an empty password.

curl --user API_KEY: http://suite.local/api/v2/internal/cron/

To run Staffjoy Suite locally, you must use Vagrant and VirtualBox. The setup process includes auto-registering an admin user via a user.txt file.

Prerequisites

• Install Virtualbox
• Install Vagrant

Initial Boot

1. Create a user.txt file in the root directory containing your email to auto-register as an admin:

   echo "your-email@example.com" > ./user.txt

2. Run the build command:

   make dev

   Note: The first run will take a long time to download base images.

Once complete, the app is accessible at http://suite.local.

Quick Launch (Existing Builds)

If the environment is already built, use:

vagrant up
vagrant ssh
cd /vagrant
make dev-server

echo "lenny@staffjoy.com" > ./user.txt
make dev

The IVR (Interactive Virtual Receptionist) currently supports only one phone number per country code. To add a new number, follow these steps:

1. Purchase a phone number in a new country code.
2. Register the following callback URLs with your telephony provider:
   • For voice calls: http(s)://(www).staffjoy.com/api/ivr/
   • For SMS: http(s)://(www).staffjoy.com/api/ivr/sms/
3. Add the new phone number to the config.py file corresponding to your target environment (Dev, Stage, or Prod).
4. Map the country code by adding it to app.constants.PHONE_COUNTRY_CODE_TO_COUNTRY.

Staffjoy Suite uses migrations to manage MySQL schema changes. Follow this workflow to update the database:

1. Modify the model: Edit app/models.py to reflect your changes.
2. Generate migration: Run make db-migrate to create the migration file.
3. Apply migration: Run make db-deploy to apply the changes to the database.

Note: Always commit your generated migration files to version control.

Resolving Migration Conflicts

If you encounter multiple migration heads, use the following commands:

python main.py db heads
# Use the resulting hashes to merge
python main.py db merge <hash1> <hash2>

Staffjoy Suite requires several environment variables for production operation. These are primarily managed in app/config.py.

Critical Security Note: Always set a unique SECRET_KEY for your application to sign cookie data. This key must be consistent across all instances in an environment.

When working with the Suite repository, be aware of the following technical limitations and behaviors:

• Development Environment Setup: The current development environment lacks a modern containerized setup (like Docker Compose) and may require manual configuration.
• Test Implementation: Tests currently rely on current_app instead of the create_app factory pattern. This may affect how you write or debug test suites.
• Session Management: The session system recreates a session when reading from a cookie. As a result, the list of active sessions in the system will appear longer than the actual number of unique users, though the implementation remains secure.

You can interact directly with the application's models and database using the shell context. This is useful for debugging, clearing data, or promoting a user to sudo status in development.

Accessing the Shell

Run the following command from the project root:

python main.py shell

Example: Granting Sudo Access

Once inside the shell, you can manipulate User objects:

print User.query.get_all()
# Find the ID from the output, then:
u = User.query.get(<id>)
u.sudo = True
db.session.commit()

python main.py shell
# Inside the shell:
u = User()
u.password = 'cat'
u.verify_password('cat')
db.session.commit()

The API uses HTTP Basic Authentication.

• Username: Your API token.
• Password: Leave blank.

Tokens are time-based and default to a 6-hour lifespan. API keys are permanent until revoked. You can retrieve a new token for your logged-in user at the /auth/api-token endpoint.

To authenticate via curl, ensure you include the trailing colon after the token to represent an empty password.

curl -u TOKEN: https://www.staffjoy.com/api/v2/

The redis service uses the redis:3.0-alpine image and runs the redis-server command. It exposes port 6379 on the host.

redis:
  image: 'redis:3.0-alpine'
  command: redis-server
  ports:
    - '6379:6379'

The db service uses the orchardup/mysql image. It is identified by the hostname mysqlserver within the Docker network.

Required environment variables:

• MYSQL_ROOT_PASSWORD: The password for the MySQL root user.
• MYSQL_DATABASE: The name of the default database to create on startup.

db:
  hostname: mysqlserver
  image: orchardup/mysql
  environment:
      MYSQL_ROOT_PASSWORD: bacon
      MYSQL_DATABASE: dev