Skip to content

Commit 5ea1e4b

Browse files
suyog19suyog19
committed
docs: add Phase 1 summary and feedback for Phase 2 planning
1 parent 5efb58d commit 5ea1e4b

1 file changed

Lines changed: 151 additions & 0 deletions

File tree

‎Phase1_Summary_and_Feedback.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Phase 1 Summary and Feedback — AI Dev Orchestrator
2+
3+
## Part 1: Phase 1 Summary
4+
5+
### What Was Built
6+
7+
A fully working orchestration backbone running on AWS EC2 (Ubuntu 22.04) with Docker Compose. The system receives Jira webhook events, persists them in PostgreSQL, dispatches stub workflows through a Redis-backed queue with concurrency control, and notifies the user at every step via Telegram.
8+
9+
**Infrastructure:**
10+
- AWS EC2 t3.small (Ubuntu 22.04 LTS)
11+
- Docker Compose stack: FastAPI app + PostgreSQL 16 + Redis 7 + worker process
12+
- nginx reverse proxy with Let's Encrypt SSL (`https://orchestrator.suyogjoshi.com`)
13+
- GitHub Actions self-hosted runner on the same EC2 VM
14+
- Auto-deploy on push to `dev`; PR-gated deploy on `main`
15+
16+
**Application (9 modules):**
17+
18+
| Module | Responsibility |
19+
|---|---|
20+
| `main.py` | FastAPI app, startup hook, debug endpoints |
21+
| `database.py` | PostgreSQL connection pool, table init with retry |
22+
| `webhooks.py` | `POST /webhooks/jira` — receive, filter, persist, dispatch |
23+
| `dispatcher.py` | Maps (issue_type, status) → workflow, creates queue entry |
24+
| `queue.py` | Redis list-based job queue |
25+
| `worker.py` | Background process, threading + semaphore for MAX_WORKERS=2 |
26+
| `workflows.py` | `story_implementation` stub (log → sleep 5s → log) |
27+
| `telegram.py` | Notification sender (startup, webhook, RUNNING, COMPLETED) |
28+
| `repo_mapping.py` | Store/retrieve issue→repo mappings (prep for Phase 2) |
29+
30+
**Database (3 tables):**
31+
- `workflow_events` — every Jira webhook event received
32+
- `workflow_runs` — lifecycle of each workflow: QUEUED → RUNNING → COMPLETED
33+
- `repo_mappings` — issue key to repo/branch mapping (Phase 2 prep)
34+
35+
**End-to-end flow that works today:**
36+
```
37+
Jira issue moved to "READY FOR DEV"
38+
→ POST https://orchestrator.suyogjoshi.com/webhooks/jira
39+
→ stored in workflow_events
40+
→ Telegram: "Story status change / READY FOR DEV"
41+
→ workflow_runs row created (QUEUED)
42+
→ job pushed to Redis
43+
→ worker picks up job → RUNNING → Telegram
44+
→ story_implementation runs (stub) → COMPLETED → Telegram
45+
```
46+
47+
**API endpoints:**
48+
49+
| Method | Path | Purpose |
50+
|---|---|---|
51+
| GET | `/healthz` | Health check |
52+
| POST | `/webhooks/jira` | Jira event receiver |
53+
| GET | `/debug/send-telegram` | Manual Telegram test |
54+
| GET/POST | `/debug/repo-mappings` | Inspect/create repo mappings |
55+
| GET | `/debug/repo-mappings/{key}` | Lookup single mapping |
56+
57+
**Scripts:**
58+
- `scripts/setup-vm.sh` — installs Docker on EC2
59+
- `scripts/setup-runner.sh` — installs GitHub Actions runner as systemd service
60+
- `scripts/setup-ssl.sh` — installs nginx + certbot, issues SSL cert
61+
62+
---
63+
64+
### Planned But Not Achieved
65+
66+
Nothing from the original 12-task plan was left incomplete. Two items were added beyond the original scope:
67+
- **Repo mapping model** — added as a Phase 2 prep step
68+
- **Main branch deploy workflow + PR protection** — the original spec mentioned it but gave no implementation details; it was fleshed out and implemented
69+
70+
---
71+
72+
### Task Completion Status
73+
74+
| Task | Description | Status |
75+
|---|---|---|
76+
| 1 | Project skeleton + `/healthz` + logging | ✅ |
77+
| 2 | Docker + Docker Compose | ✅ |
78+
| 3 | VM setup instructions (AWS EC2 Ubuntu) | ✅ |
79+
| 4 | GitHub self-hosted runner setup | ✅ |
80+
| 5 | Dev branch auto-deploy workflow | ✅ |
81+
| 6 | PostgreSQL integration | ✅ |
82+
| 7 | Telegram bot integration | ✅ |
83+
| 8 | Jira webhook endpoint | ✅ |
84+
| 9 | Event persistence | ✅ |
85+
| 10 | Workflow dispatcher (stub) | ✅ |
86+
| 11 | Redis queue + worker process | ✅ |
87+
| 12 | Stub workflow execution | ✅ |
88+
| — | Repo mapping model (bonus) | ✅ |
89+
| — | Main branch deploy + PR protection (bonus) | ✅ |
90+
91+
---
92+
93+
## Part 2: Feedback on Phase 1 Instructions
94+
95+
### Strengths
96+
97+
**1. Iterative structure was excellent.**
98+
The 12-task breakdown with explicit "DO NOT skip steps" enforced discipline. Each task was small enough to implement, test, and confirm before moving forward.
99+
100+
**2. Working style expectations were clear.**
101+
The instruction to ask before proceeding when credentials or architecture decisions are involved worked well — it prevented wrong assumptions about Telegram credentials, Jira status names, and domain setup.
102+
103+
**3. Non-goals list was valuable.**
104+
Explicitly calling out what NOT to build (PR creation, real code gen, UI) prevented scope creep throughout.
105+
106+
**4. Data model was well-specified upfront.**
107+
Having `workflow_events` and `workflow_runs` defined before implementation meant no redesign mid-build.
108+
109+
---
110+
111+
### Gaps and Issues to Address in Phase 2 Instructions
112+
113+
**1. HTTPS was not mentioned, but is mandatory for Jira Cloud.**
114+
Jira Cloud webhooks reject HTTP URLs. SSL setup was not in the task list and was discovered mid-implementation. This added an unplanned nginx + Let's Encrypt step between Tasks 8 and testing.
115+
> **Fix:** State SSL/HTTPS requirements upfront for any external-facing endpoints. Include SSL setup as an explicit task if a domain is involved.
116+
117+
**2. Trigger status name was underspecified.**
118+
The spec said "Story → Final" as the trigger condition, but this was just an example. The actual status name ("READY FOR DEV") was decided during implementation and required creating a custom Jira status. This caused back-and-forth.
119+
> **Fix:** Explicitly define all trigger conditions with exact values before implementation begins. If the value is user-defined, make that explicit and ask for it upfront.
120+
121+
**3. Tasks 8 and 9 were artificially split.**
122+
"Jira webhook endpoint" and "Event persistence" are one atomic operation — you cannot receive a webhook without persisting it. They were implemented together and the split added no value.
123+
> **Fix:** Avoid splitting tightly coupled concerns across tasks. Merge them into a single task.
124+
125+
**4. No mention of local dev limitations on Windows.**
126+
`psycopg2-binary` has DLL issues on Python 3.14/Windows, which caused confusion during local testing. All meaningful testing ended up going through Docker.
127+
> **Fix:** Explicitly state that local testing for anything touching DB or Redis should be done via `docker compose`, not local Python directly.
128+
129+
**5. GitHub repo visibility was not addressed.**
130+
Setup scripts used raw GitHub URLs which returned 404 on a private repo. The repo had to be made public mid-implementation to unblock the VM setup.
131+
> **Fix:** Specify repo visibility upfront, or provide an authentication method for private repos (e.g., use `gh` CLI to download scripts).
132+
133+
**6. Secrets and .env management on the VM was not designed upfront.**
134+
The pattern of keeping `.env.orchestrator` as a persistent file on the VM and copying it during deploy was improvised. It works but was not part of the original design.
135+
> **Fix:** Formally specify secrets management before implementation — options include a persistent `.env` file on the VM, GitHub Actions Secrets injected into the workflow, or AWS Parameter Store. Pick one and document it.
136+
137+
**7. Concurrency model was underspecified.**
138+
The spec said "max 2 parallel workflows" but did not specify the mechanism. In-process threading with a semaphore was used, but other valid approaches exist (multiple worker containers, Redis-based locking).
139+
> **Fix:** Specify the concurrency mechanism explicitly, not just the limit.
140+
141+
**8. No healthchecks for dependent services in Docker Compose.**
142+
`depends_on` only waits for containers to start, not for PostgreSQL or Redis to be ready to accept connections. Retry logic in `init_db()` was added to compensate but was not in the spec.
143+
> **Fix:** Include Docker Compose `healthcheck` definitions for `db` and `redis` services in the spec, so the app only starts when dependencies are truly ready.
144+
145+
**9. Branch strategy was not defined upfront.**
146+
The `dev`/`main` structure and PR workflow were defined during implementation rather than specified at the start.
147+
> **Fix:** Define the branching model (branch names, protection rules, merge strategy) as a prerequisite before any CI/CD tasks.
148+
149+
**10. Acceptance criteria lacked verifiable commands.**
150+
Each task's definition of done was described in prose. Verification was done manually and inconsistently.
151+
> **Fix:** For each acceptance criterion, provide an exact command that proves it passes — e.g., a `curl` command, a `psql` query, or a log grep — so there is no ambiguity about what "done" means.

0 commit comments

Comments
 (0)