Church Admin - Comprehensive Management System

Enterprise-grade church management platform for Baptists and other faith communities. Full fund accounting, member management, giving tracking, and operations.

Tech Stack: FastAPI (Python) · PostgreSQL · Redis · React · Docker · DigitalOcean

---

📋 Quick Start

Local Development (5 minutes)

# Clone the repo
git clone https://github.com/gitbuell/aiChurchFlow.git
cd aiChurchFlow

# Copy environment template
cp .env.example .env

# Start all services (Postgres, Redis, API, Frontend)
docker-compose up -d

# Wait for services to be healthy
docker-compose ps

# Access the app
# Frontend: http://localhost:3000
# API: http://localhost:8000
# API Docs: http://localhost:8000/docs

Remote Deployment (DigitalOcean)

# SSH into your DO Droplet (Ubuntu 22.04 recommended)
ssh root@your-droplet-ip

# Install Docker & Docker Compose
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Clone repo
git clone https://github.com/gitbuell/aiChurchFlow.git /opt/church-admin
cd /opt/church-admin

# Create .env from template and edit values
cp .env.example .env
nano .env  # Update with production values

# Start services
docker-compose up -d

# Verify all healthy
docker-compose ps

---

🏗️ Architecture

church-admin/
├── services/
│   ├── gateway/              # FastAPI reverse proxy (port 8000)
│   ├── people-service/       # Members, households, pastoral care (port 8001)
│   ├── finance-service/      # Donations, accounting, receipts (port 8002) [WIP]
│   ├── groups-service/       # Small groups, volunteers (port 8003) [Planned]
│   ├── events-service/       # Services, room booking (port 8004) [Planned]
│   ├── comms-service/        # Email/SMS broadcast (port 8005) [Planned]
│   ├── checkin-service/      # Child safety check-in (port 8006) [Planned]
│   └── content-service/      # Sermons, media (port 8007) [Planned]
│
├── frontend/                 # React SPA (port 3000)
├── shared/                   # Handoff schemas & audit logs
└── infra/                    # Docker, Kubernetes, Terraform

Design Principles:

• Decoupled Services: Each service is independent, scalable, replaceable
• Audit-Ready: Every write operation logged with user, timestamp, old/new values
• Encrypted: Sensitive data (pastoral notes, giving) encrypted at rest
• Production-Grade: Connection pooling, caching, error handling, graceful degradation

---

🔧 Services Overview

1. People Service (Stage 1 - Complete)

Manage members, households, and pastoral care.

Endpoints:

GET    /api/v1/members              List all members (paginated, filterable)
POST   /api/v1/members              Create new member
GET    /api/v1/members/{id}         Get single member
PATCH  /api/v1/members/{id}         Update member
DELETE /api/v1/members/{id}         Soft-delete (mark inactive)

GET    /api/v1/households           List households
POST   /api/v1/households           Create household
GET    /api/v1/households/{id}      Get household with members

POST   /api/v1/notes                Add pastoral note (encrypted)
GET    /api/v1/notes/{member_id}    Get notes for member (staff only)

Database:

• members — Core member records
• households — Family groupings
• pastoral_notes — Encrypted sensitive notes
• audit_logs — Compliance trail

---

2. Finance Service (Stage 2 - In Progress)

Donations, fund accounting, tax receipts.

Features:

• Full GAAP fund accounting (restricted/unrestricted funds)
• Donor receipt generation
• Stripe + ACH integration
• Scheduled giving
• Annual 990 export

---

3–7. Groups, Events, Comms, Check-in, Content (Stages 3–7)

Planned rollout. Each service follows the same architecture as People Service.

---

🔐 Security & Compliance

Authentication

• JWT-based on all endpoints (except health checks)
• Token expires in 24 hours (configurable)
• Roles: admin, pastor, staff, member

Encryption

• AES-256 at rest for:
  • Pastoral notes
  • Giving amounts (optional)
  • Phone numbers / addresses (optional)
• Decryption only in memory for authorized staff

Audit Logging

Every mutation (create/update/delete) logs:

• Who (user ID)
• What (entity type, ID, operation)
• When (timestamp)
• Before/After values (JSONB)
• IP address (for forensics)

-- Example audit query
SELECT * FROM audit_logs 
WHERE entity_type='member' AND operation='update'
ORDER BY timestamp DESC LIMIT 10;

---

🚀 Deployment to DigitalOcean

Option A: Single Droplet (Development)

1. Create Ubuntu 22.04 Droplet ($12–24/mo)
2. SSH in, install Docker
3. git clone + docker-compose up -d
4. Access via droplet IP on port 3000

Pros: Simple, cheap
Cons: All services on one machine; no auto-scaling

---

Option B: Kubernetes on DO (Production)

1. Create DOKS cluster ($12/mo + node costs)
2. Provision managed PostgreSQL ($15+/mo)
3. Provision managed Redis ($15+/mo)
4. Deploy services as Kubernetes workloads
5. Auto-scaling, high availability, easy updates

Kubernetes manifests coming soon in infra/k8s/

---

📊 Database Schema

Members Table

CREATE TABLE members (
  id UUID PRIMARY KEY,
  household_id UUID REFERENCES households,
  first_name VARCHAR(100) NOT NULL,
  last_name VARCHAR(100) NOT NULL,
  email VARCHAR(255) UNIQUE,
  phone VARCHAR(20),
  status ENUM('active', 'inactive', 'prospect', 'transferred', 'deceased'),
  member_since DATETIME DEFAULT NOW(),
  baptism_date DATETIME,
  birth_date DATETIME,
  address_line1 VARCHAR(255),
  city VARCHAR(100),
  state VARCHAR(50),
  zip_code VARCHAR(10),
  created_at DATETIME DEFAULT NOW(),
  updated_at DATETIME DEFAULT NOW() ON UPDATE NOW(),
  created_by UUID NOT NULL
);

CREATE INDEX idx_member_status_created ON members(status, created_at);
CREATE INDEX idx_member_household ON members(household_id);

Audit Logs Table

CREATE TABLE audit_logs (
  id UUID PRIMARY KEY,
  entity_type VARCHAR(50),        -- 'member', 'donation', etc.
  entity_id UUID,
  operation VARCHAR(20),          -- 'create', 'update', 'delete'
  user_id UUID,
  old_values JSONB,
  new_values JSONB,
  timestamp DATETIME DEFAULT NOW()
);

CREATE INDEX idx_audit_entity_timestamp ON audit_logs(entity_type, entity_id, timestamp);

---

🧪 Testing

# Run all tests
docker-compose exec people-service pytest

# Run with coverage
docker-compose exec people-service pytest --cov=app

# Run specific test
docker-compose exec people-service pytest tests/test_members.py::test_list_members

---

📝 API Documentation

Once the gateway is running, visit:

http://localhost:8000/docs

This is Swagger UI with live request/response examples.

---

🔧 Development Workflow

Making Changes to People Service

# Edit code locally (mounted in container)
vim services/people-service/app/models.py

# Services auto-reload on file changes (dev mode)
# Check logs
docker-compose logs -f people-service

# Run tests
docker-compose exec people-service pytest

Adding a New Endpoint

1. Add route in services/people-service/app/routes/members.py
2. Add schema in app/schemas.py if needed
3. Add model in app/models.py if new table
4. Test with pytest or Swagger UI
5. Commit + push

---

🐛 Troubleshooting

Services won't start

# Check logs
docker-compose logs [service-name]

# Verify database is healthy
docker-compose exec postgres psql -U church_admin -d church_db -c "SELECT 1"

# Rebuild and restart
docker-compose down
docker-compose up --build -d

Database migration errors

# Run migrations manually
docker-compose exec people-service alembic upgrade head

Can't connect to API

# Verify gateway is running
curl http://localhost:8000/health

# Check CORS settings in .env
# Default: CORS_ORIGINS=http://localhost:3000

---

📚 Next Steps

• Implement Finance Service (donations, accounting, receipts)
• Add Groups/Volunteers module
• Build Events & Scheduling
• Add Communication (Email/SMS broadcast)
• Implement Child Check-in (high-security)
• Deploy to Kubernetes on DO DOKS
• Set up monitoring (DataDog, New Relic, or open-source)
• Backup strategy (DO Spaces, automated snapshots)

---

📞 Support

For issues:

1. Check logs: docker-compose logs [service]
2. Review .env.example for missing variables
3. Verify database connectivity: docker-compose ps
4. Check Swagger UI for API errors: http://localhost:8000/docs

---

📄 License

Proprietary (Church Admin). Do not distribute without permission.

---

🙏 Built for Baptist Churches

Making church operations simple, secure, and transparent.