Problem to solve
As a developer working on Knowforge, I want a clear and agreed project folder architecture so that we can implement features faster, keep ownership boundaries clear, and reduce onboarding friction.
Right now, the project has a solid PRD and technical direction (Next.js, FastAPI, Celery/Redis, PostgreSQL/pgvector, S3-compatible storage), but no explicitly defined monorepo/service directory structure.
User experience goal
A contributor should be able to clone the repo and immediately understand where to place code for frontend, backend API, workers, shared libraries, infra, docs, and tests.
Proposal
Define and document the target folder architecture for the MVP, including:
- top-level directory layout (apps/services/packages/infra/docs/scripts)
- ownership and boundaries per folder
- where shared types/contracts live
- where tests (unit/integration/e2e) live
- env/config conventions and secrets handling boundaries
- migration path from current repo state to desired structure
Deliverables:
- Proposed directory tree (v1)
- Rationale for each top-level area
- Naming conventions
- Do/Do not contribution rules
- Follow-up implementation checklist
Further details
PRD alignment points:
- Frontend: Next.js
- Backend: FastAPI
- Workers: Celery + Redis
- Database: PostgreSQL + pgvector
- Storage: S3-compatible
- Infra: Docker + Terraform + CI/CD
- Multi-tenant isolation and security are core principles
The architecture should optimize for MVP speed while keeping a clean path to growth/enterprise phases.
Permissions and Security
- Repo write access for maintainers defining/approving structure
- Architecture decisions documented in-repo
- No secrets in repo; use env files and secret manager patterns
- Tenant-isolation-sensitive code paths clearly separated and reviewed
Feature Usage Metrics
Track adoption/impact via:
- time-to-first-contribution for a new dev
- number of cross-folder refactors needed per feature
- PR review comments about wrong folder placement
- onboarding/setup questions related to code organization
What does success look like, and how can we measure that?
Success metrics:
- 100% of new MVP features mapped to a documented folder location
- Reduced onboarding confusion (qualitative feedback)
- Fewer PR corrections for project structure mistakes
Acceptance criteria:
- Architecture doc committed with agreed folder tree
- CONTRIBUTING guidance references folder conventions
- At least one feature/task implemented following the new structure
What is the competitive advantage or differentiation for this feature?
A clean architecture improves delivery speed and quality early, which helps Knowforge ship RAG product capabilities faster with less technical debt and better tenant-safe boundaries.
Links / references
Problem to solve
As a developer working on Knowforge, I want a clear and agreed project folder architecture so that we can implement features faster, keep ownership boundaries clear, and reduce onboarding friction.
Right now, the project has a solid PRD and technical direction (Next.js, FastAPI, Celery/Redis, PostgreSQL/pgvector, S3-compatible storage), but no explicitly defined monorepo/service directory structure.
User experience goal
A contributor should be able to clone the repo and immediately understand where to place code for frontend, backend API, workers, shared libraries, infra, docs, and tests.
Proposal
Define and document the target folder architecture for the MVP, including:
Deliverables:
Further details
PRD alignment points:
The architecture should optimize for MVP speed while keeping a clean path to growth/enterprise phases.
Permissions and Security
Feature Usage Metrics
Track adoption/impact via:
What does success look like, and how can we measure that?
Success metrics:
Acceptance criteria:
What is the competitive advantage or differentiation for this feature?
A clean architecture improves delivery speed and quality early, which helps Knowforge ship RAG product capabilities faster with less technical debt and better tenant-safe boundaries.
Links / references
prd.md