Developer Getting Started Guide

Welcome to CareLog development! This guide will help you set up your development environment and understand the codebase.

Development Prerequisites

Required Software

Python 3.8+ - Programming language
Git - Version control
Code Editor - VS Code, PyCharm, or your preferred IDE
pip - Package manager (included with Python)

Recommended Tools

pytest - For running tests
Black - Code formatting
pylint - Code linting
Virtual Environment - Dependency isolation

Setting Up Development Environment

1. Clone the Repository

bash

git clone https://github.com/howweishan/carelog.git
cd carelog

2. Create Virtual Environment

Windows:

bash

python -m venv venv
.\venv\Scripts\activate

macOS/Linux:

bash

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

bash

pip install -r requirements.txt

4. Install Development Dependencies

bash

pip install pytest pytest-faker black pylint

5. Run Tests

Verify everything is set up correctly:

bash

pytest tests/ -v

You should see all tests passing.

Project Structure

carelog/
├── app.py                    # Main Streamlit application entry point
├── core/                     # Core business logic
│   ├── models/              # Data models (User, Appointment, etc.)
│   │   ├── user.py
│   │   ├── appointment.py
│   │   ├── health_log.py
│   │   └── ...
│   ├── services/            # Business logic services
│   │   ├── user_service.py
│   │   ├── health_log_service.py
│   │   └── ...
│   └── utils/               # Utility functions
│       ├── auth.py          # Authentication helpers
│       └── timeformat.py    # Time formatting utilities
├── pages/                    # Streamlit page components
│   ├── Login.py             # Login page
│   ├── Patient/             # Patient role pages
│   ├── Doctor/              # Doctor role pages
│   ├── Nurse/               # Nurse role pages
│   ├── FamilyMembers/       # Family member pages
│   └── Admin/               # Admin pages
├── data/                     # Data storage
│   ├── data.json            # Main database file
│   └── backups/             # Backup storage
├── tests/                    # Test suite
│   ├── test_services.py
│   ├── test_auth.py
│   └── ...
├── docs/                     # Documentation (this!)
├── requirements.txt          # Python dependencies
└── README.md                # Project overview

Architecture Overview

CareLog follows a layered architecture:

1. Presentation Layer (Streamlit Pages)

Located in pages/ directory
Role-based UI components
Handles user interactions
Calls service layer for business logic

2. Service Layer

Located in core/services/
Contains business logic
Validates data
Coordinates between models and database
Transaction management

3. Model Layer

Located in core/models/
Data structures and validation
Business rules
Entity definitions

4. Data Access Layer

DatabaseService in core/services/database_service.py
Handles JSON file operations
Data persistence
Query operations

Key Concepts

Data Models

All entities inherit from or follow similar patterns:

python

@dataclass
class User:
    id: str
    name: str
    email: str
    role: str
    # ... other fields

Services

Services provide CRUD operations and business logic:

python

class UserService:
    def create(self, ...): pass
    def get_by_id(self, user_id): pass
    def update(self, user_id, **kwargs): pass
    def delete(self, user_id): pass
    def list(self): pass

Database Service

Centralized JSON-based data storage:

python

db_service = DatabaseService()
db_service.update("users", user_id, user_data)
users = db_service.get("users")

Authentication

Password hashing and verification:

python

from core.utils.auth import PasswordHash

hasher = PasswordHash()
hashed = hasher.hash("password")
is_valid = hasher.verify("password", hashed)

Development Workflow

1. Feature Development

Create a feature branch

bash

git checkout -b feature/your-feature-name

Implement your changes
- Add/modify models in core/models/
- Implement service logic in core/services/
- Create UI in pages/

Write tests

bash

# Create test file in tests/
# tests/test_your_feature.py

Run tests
bash
```
pytest tests/ -v
```

Commit your changes

bash

git add .
git commit -m "Add your feature description"

2. Testing

Running All Tests

bash

pytest tests/ -v

Running Specific Test File

bash

pytest tests/test_services.py -v

Running Specific Test

bash

pytest tests/test_services.py::test_health_log_service -v

Running with Coverage

bash

pytest tests/ --cov=core --cov-report=html

3. Code Quality

Format Code

bash

black .

Lint Code

bash

pylint core/ pages/

Common Development Tasks

Adding a New Model

Create model file in core/models/
Define dataclass with fields
Add validation if needed
Export from core/models/__init__.py

Example:

python

# core/models/your_model.py
from dataclasses import dataclass

@dataclass
class YourModel:
    id: str
    name: str
    # ... other fields

Adding a New Service

Create service file in core/services/
Implement CRUD operations
Add business logic methods
Export from core/services/__init__.py

Example:

python

# core/services/your_service.py
from core.services.database_service import DatabaseService

class YourService:
    def __init__(self, db_service: DatabaseService):
        self.db = db_service
        self.collection = "your_collection"
    
    def create(self, ...):
        # Implementation
        pass

Adding a New Page

Create page file in appropriate pages/ subfolder
Import required services
Implement Streamlit UI
Handle user interactions

Example:

python

# pages/Patient/your_page.py
import streamlit as st
from core.services.your_service import YourService

st.set_page_config(page_title="Your Page")

# Check authentication
if "user" not in st.session_state:
    st.switch_page("pages/Login.py")

# Your page logic
st.title("Your Page")
# ... rest of implementation

Writing Tests

Create test file in tests/
Use pytest fixtures for setup
Write test functions
Use assertions to verify behavior

Example:

python

# tests/test_your_feature.py
import pytest
from core.services.your_service import YourService

@pytest.fixture
def temp_db():
    # Setup
    yield db, path
    # Teardown

def test_your_feature(temp_db):
    db, path = temp_db
    service = YourService(db_service=db)
    
    # Test implementation
    result = service.your_method()
    assert result is not None

Debugging

Streamlit Debugging

Use st.write() for debug output
Check browser console for JavaScript errors
Use st.session_state to inspect state

Python Debugging

Use Python debugger:
python
```
import pdb; pdb.set_trace()
```

Add logging:

python

import logging
logging.debug("Debug message")

Common Issues

Import Errors

Ensure virtual environment is activated
Verify all dependencies are installed
Check Python path

Database Errors

Verify data/data.json exists
Check file permissions
Validate JSON structure

Streamlit Page Navigation

Ensure authentication check is present
Verify role-based access control
Check session state

Best Practices

Code Style

Follow PEP 8 guidelines
Use type hints
Write docstrings for functions/classes
Keep functions small and focused

Testing

Write tests for all new features
Aim for high code coverage
Test edge cases
Use meaningful test names

Git Workflow

Create feature branches
Write clear commit messages
Keep commits atomic
Rebase before merging

Security

Never commit sensitive data
Use environment variables for secrets
Validate all user input
Follow principle of least privilege

API Reference

See API Reference for detailed API documentation.

Contributing

Pull Request Process

Fork the repository
Create a feature branch
Make your changes
Write/update tests
Update documentation
Submit pull request

Code Review Checklist

[ ] Tests pass
[ ] Code follows style guidelines
[ ] Documentation updated
[ ] No security vulnerabilities
[ ] Backward compatible (if applicable)

Developer Getting Started Guide ​

Development Prerequisites ​

Required Software ​

Recommended Tools ​

Setting Up Development Environment ​

1. Clone the Repository ​

2. Create Virtual Environment ​

3. Install Dependencies ​

4. Install Development Dependencies ​

5. Run Tests ​

Project Structure ​

Architecture Overview ​

1. Presentation Layer (Streamlit Pages) ​

2. Service Layer ​

3. Model Layer ​

4. Data Access Layer ​

Key Concepts ​

Data Models ​

Services ​

Database Service ​

Authentication ​

Development Workflow ​

1. Feature Development ​

2. Testing ​

Running All Tests ​

Running Specific Test File ​

Running Specific Test ​

Running with Coverage ​

3. Code Quality ​

Format Code ​

Lint Code ​

Common Development Tasks ​

Adding a New Model ​

Adding a New Service ​

Adding a New Page ​

Writing Tests ​

Debugging ​

Streamlit Debugging ​

Python Debugging ​

Common Issues ​

Best Practices ​

Code Style ​

Testing ​

Git Workflow ​

Security ​

API Reference ​

Contributing ​

Pull Request Process ​

Code Review Checklist ​

Resources ​

Next Steps ​

Developer Getting Started Guide

Development Prerequisites

Required Software

Recommended Tools

Setting Up Development Environment

1. Clone the Repository

2. Create Virtual Environment

3. Install Dependencies

4. Install Development Dependencies

5. Run Tests

Project Structure

Architecture Overview

1. Presentation Layer (Streamlit Pages)

2. Service Layer

3. Model Layer

4. Data Access Layer

Key Concepts

Data Models

Services

Database Service

Authentication

Development Workflow

1. Feature Development

2. Testing

Running All Tests

Running Specific Test File

Running Specific Test

Running with Coverage

3. Code Quality

Format Code

Lint Code

Common Development Tasks

Adding a New Model

Adding a New Service

Adding a New Page

Writing Tests

Debugging

Streamlit Debugging

Python Debugging

Common Issues

Best Practices

Code Style

Testing

Git Workflow

Security

API Reference

Contributing

Pull Request Process

Code Review Checklist

Resources

Next Steps